Python (agentim-agent) API

Generated from the source and its doc comments (sdk/agent-python/agentim_agent/__init__.py).

pip install agentim-agent

Functions

`child_trace`

child_trace(traceparent)

A W3C traceparent in the same trace with a new span id (docs/en/design/tracing.md); None for a missing or invalid one.

`AgentIMError`

class AgentIMError(Exception)

A refused request; code is the protocol’s error code.

`Connection`

class Connection

One WebSocket connection: requests by rid, pushes to a callback.

`Connection.open`

async open(self)

Opens the connection and waits for the welcome frame (who the agent is, its limits).

`Connection.call`

async call(self, op, **args)

Sends a request and waits for its response (raises AgentIMError).

`Connection.wait_closed`

async wait_closed(self)

Waits until the connection is closed.

`Connection.close`

async close(self)

Closes the connection.

`Stream`

class Stream

A streamed reply: await s.append(text), then await s.end().

`Stream.append`

async append(self, text)

Appends text to the stream.

`Stream.end`

async end(self)

Ends the stream: the message becomes final.

`Stream.cancel`

async cancel(self)

Cancels the stream (shown as stopped).

`Ctx`

class Ctx

What a handler gets to act in the conversation of an event.

`Ctx.config`

config(self)

The agent’s configuration now (role, skills, MCP, APIs; docs/en/design/agents.md).

`Ctx.role`

role(self)

Its role (name, description, instructions, …), or None.

`Ctx.thread_id`

thread_id(self)

The thread the message is in (its root’s id), or None: replies go there too.

`Ctx.reply`

async reply(self, text, **opts)

Replies to the message (or just sends in the conversation), in its trace and its thread.

`Ctx.stream`

async stream(self)

Starts a streamed reply to the message being handled.

`Ctx.react`

async react(self, key, msg_id=None)

Reacts to the message being handled (or msg_id) with one emoji.

`Ctx.progress`

async progress(self, kind, text, data=None)

Reports progress on the conversation being handled.

`Ctx.show_card`

async show_card(self, title, blocks, text=None)

Shows data as a card in reply (docs/en/design/chat-components.md): text, facts, table, list or your own x-… blocks.

`Ctx.ask_form`

async ask_form(self, title, fields, intro=None, submit="Send", to=None, timeout=1800.0)

Asks the person who wrote with a form card only they can fill in and waits for their answers (docs/en/design/chat-components.md): returns the values, keyed by field id.

`Ctx.steps`

async steps(self, titles, msg_id=None)

Steps people see next to the reply (docs/en/design/chat-components.md):

`Steps`

class Steps

The steps of one reply (docs/en/design/chat-components.md); each change is a progress event.

`Steps.begin`

async begin(cls, ctx, titles, msg_id=None)

Lists the steps (a plan event) and returns them.

`Steps.start`

async start(self, i, detail=None)

Step i is in progress.

`Steps.done`

async done(self, i, detail=None)

Step i is done.

`Steps.wait`

async wait(self, i, detail=None)

Step i waits (for a person: say who in detail).

`Steps.fail`

async fail(self, i, detail=None)

Step i failed (detail: why, shown to people).

`Steps.skip`

async skip(self, i, detail=None)

Step i is not needed after all.

`Agent`

class Agent

An agent: connects with its key, receives what concerns it in order (sync, then pushes), runs your handlers and acts. Delivery is at least once: a batch is acknowledged after its handlers finish.

`Agent.on_message`

on_message(self, fn)

Messages that ask this agent to act (named, replied to, or by its trigger).

`Agent.on_event`

on_event(self, fn)

Every event delivered to the agent, woken or not.

`Agent.on_card_response`

on_card_response(self, fn)

Called when a person answers one of the agent’s cards (a button or a filled form).

`Agent.on_handback`

on_handback(self, fn)

Called when the person a conversation was handed off to hands it back, with their note.

`Agent.on_reaction`

on_reaction(self, fn)

Called when someone reacts to (or un-reacts from) one of the agent’s messages:

`Agent.on_config`

on_config(self, fn)

Called with the configuration when it arrives at login and whenever it changes.

`Agent.mcp_servers`

mcp_servers(self)

The configuration’s MCP servers as agent frameworks take them (e.g. OpenAI Agents SDK’s

`Agent.write_files`

async write_files(self, dir=".", skills_dir=".claude/skills", mcp_file=".mcp.json", apis_dir=".agentim/apis")

Writes the configuration where agent frameworks look for it (docs/en/design/assistants.md): each skill as

`Agent.refresh_config`

async refresh_config(self)

Fetches the configuration again (the SDK does it on config.updated).

`Agent.start`

async start(self, start_timeout=15.0)

Connects (retrying for up to

`Agent.run`

async run(self)

Starts and runs until stop().

`Agent.stop`

async stop(self)

Stops: closes the connection; no handler runs after this.

`Agent.call`

async call(self, op, **args)

Any protocol operation (docs/en/testing.md).

`Agent.send`

async send(self, conv_id, text, reply_to=None, to=None, topics=None, intent=None,

Sends a message, with an optional envelope (to, topics, intent, refs) and sources, in the trace trace (a W3C traceparent) when given, in the thread thread_id when given. Under approval it becomes a draft (draft_id).

`Agent.react`

async react(self, conv_id, msg_id, key)

Adds a reaction (one emoji); adding it twice changes nothing.

`Agent.unreact`

async unreact(self, conv_id, msg_id, key)

Removes the agent’s reaction.

`Agent.thread`

async thread(self, conv_id, thread_id, after_seq=0, limit=None)

A thread’s root and its replies.

`Agent.pins`

async pins(self, conv_id)

The conversation’s pinned messages, latest pin first.

`Agent.ask_form`

async ask_form(self, conv_id, title, fields, intro=None, submit="Send", to=None, reply_to=None,

Sends a form card (docs/en/design/chat-components.md) and waits for its answers;

`Agent.send_card`

async send_card(self, conv_id, text, card, reply_to=None, thread_id=None)

A card (docs/en/design/agents.md); text is what clients without cards show.

`Agent.upload_file`

async upload_file(self, conv_id, name, data, mime=None)

Uploads a whole file (at most 64 MiB) to a conversation the agent is in; the server removes EXIF and GPS and makes an image’s thumbnail. Returns the file (file_id, kind, name, size, …).

`Agent.send_file`

async send_file(self, conv_id, name, data, mime=None, caption=None, reply_to=None, client_msg_id=None)

Uploads a file and sends it as an image or file message.

`Agent.file_url`

async file_url(self, conv_id, file_id, variant=None)

A link (valid 5 minutes, absolute) to read a file of a message;

`Agent.stream`

async stream(self, conv_id, reply_to=None, trace=None, thread_id=None)

Starts a streamed reply; append text, then end it. People see it as it is written and can stop it.

`Agent.progress`

async progress(self, conv_id, kind, text, msg_id=None, data=None, trace=None)

Reports progress in the side channel (thinking, plan, step, tool_call, tool_result, error), optionally tied to a message.

`Agent.ask_human`

async ask_human(self, conv_id, title, kind="approve", context=None, options=None,

Asks a person to decide and waits: {state, response, decided_by}.

`Agent.handoff`

async handoff(self, conv_id, note, to=None)

Hands the conversation to a person (its owner, or to) with a note; the agent stays quiet until it is handed back.

`Agent.history`

async history(self, conv_id, after_seq=None, before_seq=None, limit=None)

Reads the conversation’s events the agent may see, by seq (after_seq or before_seq, up to limit).

`Agent.context`

async context(self, conv_id, max_tokens=None)

The conversation for the model: stored summaries and recent messages within max_tokens.

`Agent.search`

async search(self, query, conv_id=None, limit=None)

Searches the messages the agent may see, in one conversation or all.

`Agent.put_summary`

async put_summary(self, conv_id, from_seq, to_seq, text)

Stores a summary of a range of seqs, used by context in place of those messages.

`Agent.get_state`

async get_state(self, key)

A checkpoint {key, value, version}, or None when there is none.

`Agent.put_state`

async put_state(self, key, value, version)

Writes a checkpoint; version is the one read (0 creates).

`Agent.claim`

async claim(self, msg_id)

Claims a request (intent: request) for this agent; the first claim wins, the others get conflict.

`Agent.update_task`

async update_task(self, conv_id, state, note=None)

Moves a task channel to a state (submitted, working, input_required, completed, failed, canceled) with a note.