Agents
Reference for client.agents in the Future AGI Python and TypeScript SDKs: agents.create, agents.get, agents.list, agents.update, agents.versions.create.
client.agents on fi.Client (Python) and client.agents on Client from @future-agi/sdk (TypeScript), with the nested resources client.agents.versions. The models these methods return are on Simulation response models; how arguments, pagination, errors and strict mode work is in the overview.
Methods
| Method | Description |
|---|---|
agents.create | Create a text or voice agent definition and its first active version. |
agents.get | Return an agent definition by its identifier. |
agents.list | List agent definitions in the current workspace. |
agents.update | Edit an agent definition. |
agents.versions.create | Snapshot agent configuration into a new version and activate it. |
client.agents
agents.create
Create a text or voice agent definition and its first active version. Supply agent_name, agent_type and commit_message plus the configuration required for the chosen provider.
/simulate/agent-definitions/create/ MCP tool: create_agent
result = client.agents.create(
agent_name="your-agent-name",
agent_type="voice",
commit_message="your-commit-message",
)const result = await client.agents.create({
agent_name: "your-agent-name",
agent_type: "voice",
commit_message: "your-commit-message",
}); Signature
client.agents.create(
*,
agent_name: str,
agent_type: Literal['voice', 'text'],
commit_message: str,
inbound: bool | None | NotGiven = NOT_GIVEN,
target_speaks_first: bool | None | NotGiven = NOT_GIVEN,
description: str | None | NotGiven = NOT_GIVEN,
provider: str | None | NotGiven = NOT_GIVEN,
api_key: str | None | NotGiven = NOT_GIVEN,
assistant_id: str | None | NotGiven = NOT_GIVEN,
authentication_method: Literal['api_key'] | None | NotGiven = NOT_GIVEN,
language: str | None | NotGiven = NOT_GIVEN,
languages: list[str] | None | NotGiven = NOT_GIVEN,
contact_number: str | None | NotGiven = NOT_GIVEN,
knowledge_base: str | None | NotGiven = NOT_GIVEN,
observability_enabled: bool | None | NotGiven = NOT_GIVEN,
model: str | None | NotGiven = NOT_GIVEN,
model_details: dict[str, Any] | None | NotGiven = NOT_GIVEN,
websocket_url: str | None | NotGiven = NOT_GIVEN,
websocket_headers: dict[str, Any] | None | NotGiven = NOT_GIVEN,
replay_session_id: str | None | NotGiven = NOT_GIVEN,
livekit_url: str | None | NotGiven = NOT_GIVEN,
livekit_api_key: str | None | NotGiven = NOT_GIVEN,
livekit_api_secret: str | None | NotGiven = NOT_GIVEN,
livekit_agent_name: str | None | NotGiven = NOT_GIVEN,
livekit_config_json: dict[str, Any] | None | NotGiven = NOT_GIVEN,
livekit_max_concurrency: int | None | NotGiven = NOT_GIVEN,
extra_query: dict[str, Any] | None = None,
extra_body: dict[str, Any] | None = None,
options: RequestOptions | None = None,
) -> models.AgentDefinitionCreateResponseclient.agents.create(params: AgentsCreateParams, options?: RequestOptions): Promise<models.AgentDefinitionCreateResponse>
export interface AgentsCreateParams {
agent_name: string;
agent_type: "voice" | "text";
commit_message: string;
inbound?: boolean | null;
target_speaks_first?: boolean | null;
description?: string | null;
provider?: string | null;
api_key?: string | null;
assistant_id?: string | null;
authentication_method?: "api_key" | null;
language?: string | null;
languages?: Array<string> | null;
contact_number?: string | null;
knowledge_base?: string | null;
observability_enabled?: boolean | null;
model?: string | null;
model_details?: Record<string, unknown> | null;
websocket_url?: string | null;
websocket_headers?: Record<string, unknown> | null;
replay_session_id?: string | null;
livekit_url?: string | null;
livekit_api_key?: string | null;
livekit_api_secret?: string | null;
livekit_agent_name?: string | null;
livekit_config_json?: Record<string, unknown> | null;
livekit_max_concurrency?: number | null;
} Parameters
voicetext api_key Returns
AgentDefinitionCreateResponse.
agents.get
Return an agent definition by its identifier.
/simulate/agent-definitions/{agent_id}/ MCP tool: get_agent
result = client.agents.get("your-agent-id")const result = await client.agents.get("your-agent-id"); Signature
client.agents.get(
agent_id: str,
*,
extra_query: dict[str, Any] | None = None,
options: RequestOptions | None = None,
) -> models.AgentDefinitionDetailResponseclient.agents.get(agentId: string, options?: RequestOptions): Promise<models.AgentDefinitionDetailResponse> Parameters
Positional argument agent_id.
Returns
AgentDefinitionDetailResponse.
agents.list
List agent definitions in the current workspace.
/simulate/agent-definitions/ Paginated: returns a pager (how pagination works) · MCP tool: list_agents
for item in client.agents.list():
print(item)for await (const item of client.agents.list()) {
console.log(item);
} Signature
client.agents.list(
*,
search: str | None | NotGiven = NOT_GIVEN,
agent_type: Literal['voice', 'text'] | None | NotGiven = NOT_GIVEN,
agent_definition_id: str | None | NotGiven = NOT_GIVEN,
limit: int | None | NotGiven = NOT_GIVEN,
extra_query: dict[str, Any] | None = None,
options: RequestOptions | None = None,
) -> SyncPager[models.AgentDefinitionListResponse]client.agents.list(params: AgentsListParams = {}, options?: RequestOptions): Pager<models.AgentDefinitionListResponse>
export interface AgentsListParams {
search?: string | null;
agent_type?: "voice" | "text" | null;
agent_definition_id?: string | null;
limit?: number | null;
} Parameters
voicetext The pager sends page itself; pass limit to change the page size.
Returns
A pager of AgentDefinitionListResponse items: iterate it, or call to_list() (Python) / toArray() (TypeScript).
agents.update
Edit an agent definition. Leave observability_enabled out to keep observability as it is; send true or false to turn it on or off. To use changed configuration in a versioned simulation, subsequently call create_agent_version, or supply the changes directly to create_agent_version.
/simulate/agent-definitions/{agent_id}/edit/ MCP tool: update_agent
result = client.agents.update("your-agent-id")const result = await client.agents.update("your-agent-id"); Signature
client.agents.update(
agent_id: str,
*,
observability_enabled: bool | None | NotGiven = NOT_GIVEN,
agent_name: str | None | NotGiven = NOT_GIVEN,
agent_type: Literal['voice', 'text'] | None | NotGiven = NOT_GIVEN,
description: str | None | NotGiven = NOT_GIVEN,
provider: str | None | NotGiven = NOT_GIVEN,
api_key: str | None | NotGiven = NOT_GIVEN,
assistant_id: str | None | NotGiven = NOT_GIVEN,
authentication_method: Literal['api_key'] | None | NotGiven = NOT_GIVEN,
language: str | None | NotGiven = NOT_GIVEN,
languages: list[str] | None | NotGiven = NOT_GIVEN,
contact_number: str | None | NotGiven = NOT_GIVEN,
inbound: bool | None | NotGiven = NOT_GIVEN,
target_speaks_first: bool | None | NotGiven = NOT_GIVEN,
knowledge_base: str | None | NotGiven = NOT_GIVEN,
model: str | None | NotGiven = NOT_GIVEN,
model_details: dict[str, Any] | None | NotGiven = NOT_GIVEN,
websocket_url: str | None | NotGiven = NOT_GIVEN,
websocket_headers: dict[str, Any] | None | NotGiven = NOT_GIVEN,
livekit_url: str | None | NotGiven = NOT_GIVEN,
livekit_api_key: str | None | NotGiven = NOT_GIVEN,
livekit_api_secret: str | None | NotGiven = NOT_GIVEN,
livekit_agent_name: str | None | NotGiven = NOT_GIVEN,
livekit_config_json: dict[str, Any] | None | NotGiven = NOT_GIVEN,
livekit_max_concurrency: int | None | NotGiven = NOT_GIVEN,
extra_query: dict[str, Any] | None = None,
extra_body: dict[str, Any] | None = None,
options: RequestOptions | None = None,
) -> models.AgentDefinitionEditResponseclient.agents.update(agentId: string, params: AgentsUpdateParams = {}, options?: RequestOptions): Promise<models.AgentDefinitionEditResponse>
export interface AgentsUpdateParams {
observability_enabled?: boolean | null;
agent_name?: string | null;
agent_type?: "voice" | "text" | null;
description?: string | null;
provider?: string | null;
api_key?: string | null;
assistant_id?: string | null;
authentication_method?: "api_key" | null;
language?: string | null;
languages?: Array<string> | null;
contact_number?: string | null;
inbound?: boolean | null;
target_speaks_first?: boolean | null;
knowledge_base?: string | null;
model?: string | null;
model_details?: Record<string, unknown> | null;
websocket_url?: string | null;
websocket_headers?: Record<string, unknown> | null;
livekit_url?: string | null;
livekit_api_key?: string | null;
livekit_api_secret?: string | null;
livekit_agent_name?: string | null;
livekit_config_json?: Record<string, unknown> | null;
livekit_max_concurrency?: number | null;
} Parameters
Positional argument agent_id.
voicetext api_key Returns
client.agents.versions
TypeScript: client.agents.versions.
agents.versions.create
Snapshot agent configuration into a new version and activate it. Can also update agent configuration. Use the returned version when creating a simulation test; existing tests may remain pinned to an older version.
/simulate/agent-definitions/{agent_id}/versions/create/ MCP tool: create_agent_version
result = client.agents.versions.create("your-agent-id")const result = await client.agents.versions.create("your-agent-id"); Signature
client.agents.versions.create(
agent_id: str,
*,
agent_name: str | None | NotGiven = NOT_GIVEN,
agent_type: Literal['voice', 'text'] | None | NotGiven = NOT_GIVEN,
description: str | None | NotGiven = NOT_GIVEN,
provider: str | None | NotGiven = NOT_GIVEN,
api_key: str | None | NotGiven = NOT_GIVEN,
assistant_id: str | None | NotGiven = NOT_GIVEN,
authentication_method: Literal['api_key'] | None | NotGiven = NOT_GIVEN,
language: str | None | NotGiven = NOT_GIVEN,
languages: list[str] | None | NotGiven = NOT_GIVEN,
contact_number: str | None | NotGiven = NOT_GIVEN,
inbound: bool | None | NotGiven = NOT_GIVEN,
target_speaks_first: bool | None | NotGiven = NOT_GIVEN,
knowledge_base: str | None | NotGiven = NOT_GIVEN,
model: str | None | NotGiven = NOT_GIVEN,
model_details: dict[str, Any] | None | NotGiven = NOT_GIVEN,
livekit_url: str | None | NotGiven = NOT_GIVEN,
livekit_api_key: str | None | NotGiven = NOT_GIVEN,
livekit_api_secret: str | None | NotGiven = NOT_GIVEN,
livekit_agent_name: str | None | NotGiven = NOT_GIVEN,
livekit_config_json: dict[str, Any] | None | NotGiven = NOT_GIVEN,
livekit_max_concurrency: int | None | NotGiven = NOT_GIVEN,
commit_message: str | None | NotGiven = NOT_GIVEN,
observability_enabled: bool | None | NotGiven = NOT_GIVEN,
extra_query: dict[str, Any] | None = None,
extra_body: dict[str, Any] | None = None,
options: RequestOptions | None = None,
) -> models.AgentVersionCreateResponseclient.agents.versions.create(agentId: string, params: AgentsVersionsCreateParams = {}, options?: RequestOptions): Promise<models.AgentVersionCreateResponse>
export interface AgentsVersionsCreateParams {
agent_name?: string | null;
agent_type?: "voice" | "text" | null;
description?: string | null;
provider?: string | null;
api_key?: string | null;
assistant_id?: string | null;
authentication_method?: "api_key" | null;
language?: string | null;
languages?: Array<string> | null;
contact_number?: string | null;
inbound?: boolean | null;
target_speaks_first?: boolean | null;
knowledge_base?: string | null;
model?: string | null;
model_details?: Record<string, unknown> | null;
livekit_url?: string | null;
livekit_api_key?: string | null;
livekit_api_secret?: string | null;
livekit_agent_name?: string | null;
livekit_config_json?: Record<string, unknown> | null;
livekit_max_concurrency?: number | null;
commit_message?: string | null;
observability_enabled?: boolean | null;
} Parameters
Positional argument agent_id.
voicetext api_key Returns
Questions & Discussion