Template Agents

Use existing agents from your workspace.

Basic Usage

1from inferencesh import inference23client = inference(api_key="inf_your_key")45# Reference by namespace/name@version6agent = client.agent("my-team/support-agent@latest")78# Send a message9response = agent.send_message("Hello!")10print(response.text)

Agent Reference Formats

1# Latest version2namespace/agent-name@latest34# Specific version5namespace/agent-name@abc123

Per-chat context

Agents with call tools that use {{context.X}} in URL templates need context values when you start a chat. Declare fields in the agent config, then pass values on the first message — equivalent to the CLI's --context key=value. Required context must be provided or the agent will not run.

1agent = client.agent(2    "my-team/pricing-agent@latest",3    context={"version_id": "v1", "app_id": "app_123"},4)56response = agent.send_message("Show me the current pricing")

Context is set once per chat and cannot change, so every tool call in that conversation uses the same values.

→ Context in call tools · Adding tools · Create chat REST API

File attachments

Send images, documents, or other files with a message. The SDK uploads them and attaches FileRef URIs to the user message.

1# Paths, bytes, or data URIs — uploaded automatically2response = agent.send_message(3    "What's in this image?",4    files=[open("photo.png", "rb").read()],5)67# upload_file returns a FileRef (uri, filename, content_type) for logging or custom flows8ref = agent.upload_file(open("doc.pdf", "rb").read(), filename="doc.pdf")9response = agent.send_message("Summarize this PDF", files=[open("doc.pdf", "rb").read()])

→ Files API · Python SDK file attachments · JavaScript SDK file attachments

Multi-turn Conversations

State is maintained automatically:

1agent = client.agent("my-team/support-agent@latest")23response1 = agent.send_message("What's my account status?")4print(response1.text)56response2 = agent.send_message("Can you explain that more?")7print(response2.text)  # Has context from previous message

Reset Conversation

Start a new conversation. reset() clears the SDK's chat ID so the next sendMessage creates a fresh chat.

When a chat is created, the platform pins the resolved agent version on it (agent_version_id). Continuing the same chat always runs that version — redeploying the agent or changing @latest in your code does not upgrade an open conversation. Call reset() (or start a new chat via REST without chat_id) to pick up the latest definition, including updated tool schemas.

1agent.reset()23response = agent.send_message("Start fresh!")

Get Chat History

Message history is not included in GET /chats/:id or agent.getChat(). Fetch messages with the REST List chat messages endpoint (GET /chats/:id/messages). When streaming, chat_messages events deliver updates in real time.

With AgentChatProvider / useAgentChat, the SDK loads messages automatically when connecting or polling (metadata from GET /chats/:id, then GET /chats/:id/messages when the response has no chat_messages). The initial load uses the server default page size (50 newest messages) — not the full transcript. Hook state (chat.chat_messages) stays populated without extra calls; stream events append new messages during an active run.

Scroll-back pagination (v0.6.41+): when hasOlderMessages is true, call loadOlderMessages() from useAgentActions() to fetch the next page. The SDK prepends deduplicated messages and updates the internal cursor. Trigger this when the user scrolls near the top of your message list:

1const { messages } = useAgentChat();2const { loadOlderMessages, hasOlderMessages } = useAgentActions();34// e.g. on scroll near top5if (hasOlderMessages) {6  await loadOlderMessages(); // returns true when more pages remain7}

For imperative or non-React UIs, paginate with cursor or pass limit=-1 via the REST API (examples below).

1# REST: list messages (newest first by default)2messages = client.http.request(3    "get", f"/chats/{chat_id}/messages", params={"limit": -1}4).data["items"]56for message in messages:7    print(f"{message['role']}: {message['content']}")

Stop Active Response

1# Start streaming2for chunk in agent.send_message("Tell me a story", stream=True):3    if should_stop:4        agent.stop()5        break6    print(chunk.text)