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

MethodDescription
agents.createCreate a text or voice agent definition and its first active version.
agents.getReturn an agent definition by its identifier.
agents.listList agent definitions in the current workspace.
agents.updateEdit an agent definition.
agents.versions.createSnapshot 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.

POST /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.AgentDefinitionCreateResponse
client.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

agent_name string Required
agent_type string Required
Allowed values:
voicetext
commit_message string Required
inbound boolean Optional
target_speaks_first boolean Optional
description string Optional
provider string Optional
api_key string Optional
assistant_id string Optional
authentication_method string Optional
Allowed values:
api_key
language string Optional
languages string[] Optional
contact_number string Optional
knowledge_base string Optional
observability_enabled boolean Optional
model string Optional
model_details object Optional
websocket_url string Optional
websocket_headers object Optional
replay_session_id string Optional
livekit_url string Optional
livekit_api_key string Optional
livekit_api_secret string Optional
livekit_agent_name string Optional
livekit_config_json object Optional
livekit_max_concurrency integer Optional

Returns

AgentDefinitionCreateResponse.

agents.get

Return an agent definition by its identifier.

GET /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.AgentDefinitionDetailResponse
client.agents.get(agentId: string, options?: RequestOptions): Promise<models.AgentDefinitionDetailResponse>

Parameters

agent_id string Required

Positional argument agent_id.

Returns

AgentDefinitionDetailResponse.

agents.list

List agent definitions in the current workspace.

GET /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

search string Optional
agent_type string Optional
Allowed values:
voicetext
agent_definition_id string Optional
limit integer Optional

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.

PUT /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.AgentDefinitionEditResponse
client.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

agent_id string Required

Positional argument agent_id.

observability_enabled boolean Optional
agent_name string Optional
agent_type string Optional
Allowed values:
voicetext
description string Optional
provider string Optional
api_key string Optional
assistant_id string Optional
authentication_method string Optional
Allowed values:
api_key
language string Optional
languages string[] Optional
contact_number string Optional
inbound boolean Optional
target_speaks_first boolean Optional
knowledge_base string Optional
model string Optional
model_details object Optional
websocket_url string Optional
websocket_headers object Optional
livekit_url string Optional
livekit_api_key string Optional
livekit_api_secret string Optional
livekit_agent_name string Optional
livekit_config_json object Optional
livekit_max_concurrency integer Optional

Returns

AgentDefinitionEditResponse.

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.

POST /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.AgentVersionCreateResponse
client.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

agent_id string Required

Positional argument agent_id.

agent_name string Optional
agent_type string Optional
Allowed values:
voicetext
description string Optional
provider string Optional
api_key string Optional
assistant_id string Optional
authentication_method string Optional
Allowed values:
api_key
language string Optional
languages string[] Optional
contact_number string Optional
inbound boolean Optional
target_speaks_first boolean Optional
knowledge_base string Optional
model string Optional
model_details object Optional
livekit_url string Optional
livekit_api_key string Optional
livekit_api_secret string Optional
livekit_agent_name string Optional
livekit_config_json object Optional
livekit_max_concurrency integer Optional
commit_message string Optional
observability_enabled boolean Optional

Returns

AgentVersionCreateResponse.

Was this page helpful?

Questions & Discussion