> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryprofound.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents

> Agent エンドポイントのサンプルリクエスト。

このガイドでは、一般的な Agent API リクエストの実践的な例を紹介します。すべての例で API キーによる認証が必要です。

<Note>
  `your_api_key`、`your_agent_id`、`your_run_id` を実際の値に置き換えてください。まず一覧エンドポイントを使用して、組織で利用可能な Agents を確認してください。
</Note>

## Starter Template のウォークスルー

**Profound の Starter Template** を使用して Agent を作成したとします。この Agent には、**Any Text (This is an example input)** というラベルの必須テキスト入力が 1 つあります。

一般的な流れは次のとおりです。

1. [**List Agents**](/api-reference/agents/list-agents) を使用して Agent ID を確認します。
2. [**Get an Agent**](/api-reference/agents/get-an-agent) を使用して入力スキーマを確認します。
3. スキーマのプロパティ名をキーとする `inputs` オブジェクトを指定して、[**Run an Agent**](/api-reference/agents/run-an-agent) を使用します。
4. [**Get an Agent Run**](/api-reference/agents/get-an-agent-run) を使用して、実行が成功したか失敗したかを確認します。

### 1. List Agents

まず、実行したい Agent を特定します。

```http theme={null}
GET /v1/agents?statuses=published&limit=100 HTTP/1.1
X-API-Key: your_api_key
```

```json theme={null}
{
  "data": [
    {
      "id": "your_agent_id",
      "organization_id": "your_organization_id",
      "name": "Starter Template",
      "status": "published",
      "created_at": "2026-04-24T19:03:15.459951Z",
      "description": "This template is a simple starter agent that helps you get familiar with how the tool works. Try it out, customize it, and then build your own!"
    }
  ]
}
```

### 2. Get an Agent

次に、Agent を取得してスキーマを確認します。このレスポンスでは、Agent の入力スキーマと出力スキーマが JSON Schema として返されます。`schema.input` を使用して、どのフィールドが必須か、また Agent の実行時に `inputs` オブジェクトでどの変数 ID を送信するかを判断します。`schema.output` を使用して、実行から返される結果の構造を把握することもできます。

```http theme={null}
GET /v1/agents/your_agent_id?version=published HTTP/1.1
X-API-Key: your_api_key
```

```json theme={null}
{
  "id": "your_agent_id",
  "organization_id": "your_organization_id",
  "name": "Starter Template",
  "status": "published",
  "created_at": "2026-04-24T19:03:15.459951Z",
  "description": "This template is a simple starter agent that helps you get familiar with how the tool works. Try it out, customize it, and then build your own!",
  "schema": {
    "input": {
      "type": "object",
      "properties": {
        "your_input_variable_id": {
          "type": "string",
          "title": "Any Text (This is an example input)"
        }
      },
      "additionalProperties": false,
      "description": "Provide inputs as an object keyed by variable ID.",
      "required": ["your_input_variable_id"]
    },
    "output": {
      "type": "object",
      "properties": {
        "your_output_variable_id": {
          "type": "string",
          "title": "Example LLM Output"
        }
      },
      "additionalProperties": false,
      "description": "Agent outputs are returned as an object keyed by variable ID."
    }
  }
}
```

<Tip>
  `inputs` オブジェクトでは、スキーマのプロパティキーをフィールド名として使用する必要があります。この例では、必須の入力キーは人が読めるラベルではなく `your_input_variable_id` です。
</Tip>

### 3. Run an Agent

次に、その入力キーを使用して実行を開始します。

```http theme={null}
POST /v1/agents/your_agent_id/runs HTTP/1.1
Content-Type: application/json
X-API-Key: your_api_key

{
  "inputs": {
    "your_input_variable_id": "<your_input_value>"
  }
}
```

```json theme={null}
{
  "id": "your_run_id",
  "agent_id": "your_agent_id",
  "status": "queued",
  "started_at": "2026-04-24T19:08:34.495737Z"
}
```

<Info>
  このエンドポイントは `202 Accepted` を返します。送信が成功しても、実行が受け付けられたことを意味するだけです。最終的に成功したか失敗したかを確認するには、実行を取得する必要があります。
</Info>

### 4. Get an Agent Run

最後に、実行結果を取得します。

```http theme={null}
GET /v1/agents/your_agent_id/runs/your_run_id HTTP/1.1
X-API-Key: your_api_key
```

```json theme={null}
{
  "id": "your_run_id",
  "agent_id": "your_agent_id",
  "status": "succeeded",
  "started_at": "2026-04-24T20:53:08.241633Z",
  "finished_at": "2026-04-24T20:53:09.314671Z",
  "outputs": {
    "your_output_variable_id": "<your_output_value>"
  }
}
```