# Agents
## Agent Integration Guide
This section describes the basics of using the Agents API to integrate your parcelLab agent into your application or chat interfaces.
### Requirements
Before you start, ensure the following prerequisites are met:
* OpenAI opt-in enabled for your parcelLab account
* parcelLab API access
* Credentials required: parcelLab account ID and API token with `read` and `write` scopes
* An agent configured for your account.\
The agent ID for your parcelLab agent is required for using the API and will be provided after the agent is configured for your account.
How to opt in to OpenAI for your parcelLab account
To use the Agents API, you must opt in to enable OpenAI for your account.
1. Log in to the parcelLab App.
2. Navigate to **Admin** > **Accounts**.\
A list of accounts you have access to will display with the name and ID for each record.
3. Select the account you want to enable the OpenAI opt-in for.
4. In the **Opt ins** section, select the **OpenAI** checkbox.
5. Click **Save**.\
The OpenAI opt-in is saved for your parcelLab account.
### Using the Agents API
{% hint style="success" %}
To [authenticate your API requests](/docs/developers/getting-started/authentication.md#authentication-process), please provide your API token in the request header.
{% endhint %}
{% stepper %}
{% step %}
**Start agent execution**
Start by making a request to the agent execution endpoint (that is: `v4/agents/{agent_id}/execute`) using your agent ID. The response will include a thread ID, which is used to identify a message thread with your agent.
{% endstep %}
{% step %}
**Poll the thread status**
Using your agent ID and thread ID, you can call the `v4/agents/{agent_id}/threads/{thread_ref}` endpoint to retrieve the status of the agent execution. When the execution status is `completed`, display the message from the agent’s response.
{% endstep %}
{% step %}
**Submit messages to an existing thread**
When the end-user sends a message, you can call the `v4/agents/{agent_id}/threads/{thread_ref}/messages` endpoint to add it to the existing thread. Repeat the polling until the execution status is `complete`.
{% endstep %}
{% endstepper %}
{% hint style="warning" %}
**Response Time**: The WISMO Agent does not stream responses. Response times may vary depending on the complexity of the query. For chat-based implementations, consider showing a "typing" indicator while polling for results.
{% endhint %}
{% hint style="success" %}
**Best Practice**: Implement a polling mechanism with exponential backoff to avoid excessive API calls while waiting for responses.
{% endhint %}
## Agents API Reference
These requests allow you to start message threads with your pre-configured agent and submit messages to existing threads.
### Start Asynchronous Agent Execution
You can start a thread with the agent using the `v4/agents/{agent_id}/execute` endpoint.
## Start async agent execution
> Starts agent execution asynchronously and returns a thread reference immediately. Use the thread reference to poll for results.
```json
{"openapi":"3.1.0","info":{"title":"parcelLab API","version":"v4"},"security":[{"OAuth2 Authentication":[]},{"HeaderToken":[]}],"components":{"securitySchemes":{"OAuth2 Authentication":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"HeaderToken":{"type":"http","scheme":"bearer","bearerFormat":"Parcellab-API-Token base64(account_id:token)","description":"Send `Authorization: Parcellab-API-Token `.\n\n`` = `base64(account_id:token)` as provided in the portal."}},"schemas":{"PublicAgentExecuteRequest":{"type":"object","description":"Payload for starting async agent execution.","properties":{"query":{"type":"string","minLength":1,"description":"The user's input query"},"context":{"type":"object","description":"Optional context data for the agent"}},"required":["query"]},"PublicAgentThreadResponse":{"type":"object","description":"Response for async agent execution.","properties":{"threadId":{"type":"string","description":"External reference ID of the thread"},"executionStatus":{"type":"string","description":"Current execution status"}},"required":["executionStatus","threadId"]},"Error400Response":{"type":"object","properties":{"type":{"type":"string"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/GenericErrorItem"}}},"required":["errors","type"]},"GenericErrorItem":{"type":"object","properties":{"code":{"type":"string"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["code","detail"]},"ErrorResponse403":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/ClientErrorEnum"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error403"}}},"required":["errors","type"]},"ClientErrorEnum":{"enum":["client_error"],"type":"string","description":"* `client_error` - Client Error"},"Error403":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode403Enum"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["attr","code","detail"]},"ErrorCode403Enum":{"enum":["permission_denied"],"type":"string","description":"* `permission_denied` - Permission Denied"},"ErrorResponse404":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/ClientErrorEnum"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error404"}}},"required":["errors","type"]},"Error404":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode404Enum"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["attr","code","detail"]},"ErrorCode404Enum":{"enum":["not_found"],"type":"string","description":"* `not_found` - Not Found"}}},"paths":{"/v4/agents/{agent_id}/execute/":{"post":{"operationId":"agents_execute_create","description":"Starts agent execution asynchronously and returns a thread reference immediately. Use the thread reference to poll for results.","summary":"Start async agent execution","parameters":[{"in":"path","name":"agent_id","schema":{"type":"string","format":"uuid","description":"External ID of this agent, used on the simple agent thread API"},"required":true}],"tags":["Agents"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAgentExecuteRequest"}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/PublicAgentExecuteRequest"}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/PublicAgentExecuteRequest"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAgentThreadResponse"}}},"description":""},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400Response"}}},"description":""},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse403"}}},"description":""},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"description":""}}}}}}
```
### Get Thread Status and Messages
You can retrieve the current status and messages of an agent thread using the `v4/agents/{agent_id}/threads/{thread_ref}` endpoint.
## Get thread status and messages
> Retrieve the current status and messages of an agent thread.
```json
{"openapi":"3.1.0","info":{"title":"parcelLab API","version":"v4"},"security":[{"OAuth2 Authentication":[]},{"HeaderToken":[]}],"components":{"securitySchemes":{"OAuth2 Authentication":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"HeaderToken":{"type":"http","scheme":"bearer","bearerFormat":"Parcellab-API-Token base64(account_id:token)","description":"Send `Authorization: Parcellab-API-Token `.\n\n`` = `base64(account_id:token)` as provided in the portal."}},"schemas":{"PublicSimpleAgentThreadDetail":{"type":"object","description":"Public-facing thread details with limited message info.","properties":{"id":{"type":"integer","readOnly":true},"externalReferenceId":{"type":"string","readOnly":true},"account":{"type":"integer"},"agent":{"type":"string","format":"uuid","description":"External ID of this agent, used on the simple agent thread API"},"user":{"type":"integer","readOnly":true},"executionStatus":{"$ref":"#/components/schemas/ExecutionStatusEnum"},"contentType":{"type":["string","null"],"title":"Python model class name","description":"Lowercased Django model name of the linked object (e.g. 'layout', 'tracking'). Pair with object_id."},"objectId":{"type":"string","maxLength":255},"createdAt":{"type":"string","format":"date-time","readOnly":true},"updatedAt":{"type":"string","format":"date-time","readOnly":true},"messages":{"items":{"anyOf":[{"$ref":"#/components/schemas/InputMessage"},{"$ref":"#/components/schemas/OutputMessage"}]},"type":"array"},"progressText":{"type":"string","readOnly":true},"progressReasoning":{"type":"string","readOnly":true}},"required":["account","agent","createdAt","externalReferenceId","id","messages","progressReasoning","progressText","updatedAt","user"]},"ExecutionStatusEnum":{"enum":["idle","running","completed","failed"],"type":"string","description":"* `idle` - Idle\n* `running` - Running\n* `completed` - Completed\n* `failed` - Failed"},"InputMessage":{"properties":{"type":{"const":"input_message","default":"input_message","title":"Type","type":"string"},"context":{"additionalProperties":true,"title":"Context","type":"object"},"query":{"title":"Query","type":"string"}},"required":["query"],"title":"InputMessage","type":"object"},"OutputMessage":{"properties":{"id":{"title":"Id","type":"string"},"type":{"allOf":[{"$ref":"#/components/schemas/OutputMessageTypeEnum"}],"default":"response","title":"Type"},"response":{"title":"Response","type":"string"},"data":{"additionalProperties":true,"default":{},"title":"Data","type":"object"}},"required":["response"],"title":"OutputMessage","type":"object"},"OutputMessageTypeEnum":{"enum":["response","rejection"],"type":"string"},"Error400Response":{"type":"object","properties":{"type":{"type":"string"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/GenericErrorItem"}}},"required":["errors","type"]},"GenericErrorItem":{"type":"object","properties":{"code":{"type":"string"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["code","detail"]},"ErrorResponse403":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/ClientErrorEnum"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error403"}}},"required":["errors","type"]},"ClientErrorEnum":{"enum":["client_error"],"type":"string","description":"* `client_error` - Client Error"},"Error403":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode403Enum"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["attr","code","detail"]},"ErrorCode403Enum":{"enum":["permission_denied"],"type":"string","description":"* `permission_denied` - Permission Denied"},"ErrorResponse404":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/ClientErrorEnum"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error404"}}},"required":["errors","type"]},"Error404":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode404Enum"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["attr","code","detail"]},"ErrorCode404Enum":{"enum":["not_found"],"type":"string","description":"* `not_found` - Not Found"}}},"paths":{"/v4/agents/{agent_id}/threads/{thread_ref}/":{"get":{"operationId":"agents_threads_retrieve","description":"Retrieve the current status and messages of an agent thread.","summary":"Get thread status and messages","parameters":[{"in":"path","name":"agent_id","schema":{"type":"string","format":"uuid","description":"External ID of this agent, used on the simple agent thread API"},"required":true},{"in":"path","name":"thread_ref","schema":{"type":"string"},"description":"External reference ID of the thread","required":true}],"tags":["Agents"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicSimpleAgentThreadDetail"}}},"description":""},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400Response"}}},"description":""},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse403"}}},"description":""},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"description":""}}}}}}
```
### Submit Message to Existing Thread
You can submit messages to existing threads using the `v4/agents/{agent_id}/threads/{thread_ref}/messages` endpoint.
## Add message to existing thread
> Async add a new message to an existing thread.
```json
{"openapi":"3.1.0","info":{"title":"parcelLab API","version":"v4"},"security":[{"OAuth2 Authentication":[]},{"HeaderToken":[]}],"components":{"securitySchemes":{"OAuth2 Authentication":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"HeaderToken":{"type":"http","scheme":"bearer","bearerFormat":"Parcellab-API-Token base64(account_id:token)","description":"Send `Authorization: Parcellab-API-Token `.\n\n`` = `base64(account_id:token)` as provided in the portal."}},"schemas":{"PublicAgentExecuteRequest":{"type":"object","description":"Payload for starting async agent execution.","properties":{"query":{"type":"string","minLength":1,"description":"The user's input query"},"context":{"type":"object","description":"Optional context data for the agent"}},"required":["query"]},"PublicAgentThreadResponse":{"type":"object","description":"Response for async agent execution.","properties":{"threadId":{"type":"string","description":"External reference ID of the thread"},"executionStatus":{"type":"string","description":"Current execution status"}},"required":["executionStatus","threadId"]},"Error400Response":{"type":"object","properties":{"type":{"type":"string"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/GenericErrorItem"}}},"required":["errors","type"]},"GenericErrorItem":{"type":"object","properties":{"code":{"type":"string"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["code","detail"]},"ErrorResponse403":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/ClientErrorEnum"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error403"}}},"required":["errors","type"]},"ClientErrorEnum":{"enum":["client_error"],"type":"string","description":"* `client_error` - Client Error"},"Error403":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode403Enum"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["attr","code","detail"]},"ErrorCode403Enum":{"enum":["permission_denied"],"type":"string","description":"* `permission_denied` - Permission Denied"},"ErrorResponse404":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/ClientErrorEnum"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error404"}}},"required":["errors","type"]},"Error404":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode404Enum"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["attr","code","detail"]},"ErrorCode404Enum":{"enum":["not_found"],"type":"string","description":"* `not_found` - Not Found"}}},"paths":{"/v4/agents/{agent_id}/threads/{thread_ref}/messages/":{"post":{"operationId":"agents_threads_messages_create","description":"Async add a new message to an existing thread.","summary":"Add message to existing thread","parameters":[{"in":"path","name":"agent_id","schema":{"type":"string","format":"uuid","description":"External ID of this agent, used on the simple agent thread API"},"required":true},{"in":"path","name":"thread_ref","schema":{"type":"string"},"description":"External reference ID of the thread","required":true}],"tags":["Agents"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAgentExecuteRequest"}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/PublicAgentExecuteRequest"}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/PublicAgentExecuteRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicAgentThreadResponse"}}},"description":""},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400Response"}}},"description":""},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse403"}}},"description":""},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"description":""}}}}}}
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.parcellab.com/docs/developers/agents/agents.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.