Agent.
Define named, reusable personas with instructions, purpose, and metadata.
An Agent is a named, reusable persona with optional instructions, context, purpose, and metadata. You can pass a plain dict with the same keys anywhere an Agent is accepted — the SDK normalises it.
Agent class
from matilda_agent_sdk import Agent
reviewer = Agent(
name="code-reviewer",
purpose="code",
instructions="Review code for correctness, security, and readability.",
context="Project: matilda-core\nLanguage: Python",
metadata={"team": "platform"},
)The Agent is reusable — construct once, run many times.
Constructor parameters
| Field | type | description |
|---|---|---|
| name | str | Agent name. Must be non-empty (raises ValueError otherwise). Required. |
| instructions | AgentInstructions | Static string or dynamic callable (see below). |
| context | str | None | Additional context appended to instructions under a Context: header. |
| purpose | AgentPurpose | Controls the default response_mode and how the server routes the request. Defaults to 'code'. |
| response_mode | str | None | Override the response mode. If omitted, derived from purpose. |
| metadata | dict | Custom data available to dynamic instructions. Defaults to {}. |
AgentPurpose
AgentPurpose = Literal["code", "analysis", "general"]| Purpose | response_mode default |
|---|---|
'code' | 'auto' |
'analysis' | 'deep' |
'general' | 'auto' |
Dynamic instructions
Instructions can be a callable that receives a runtime context dict, letting you customise behaviour per-call (async callables are awaited):
from matilda_agent_sdk import Agent, run
def reviewer_instructions(ctx):
lang = ctx["metadata"].get("language", "auto-detect")
strictness = ctx["metadata"].get("strictness", "normal")
return "\n".join(
[
"Review the following code.",
f"Language: {lang}",
f"Strictness: {strictness}",
"Focus on: correctness, security, and readability.",
]
)
agent = Agent(name="code-reviewer", purpose="code", instructions=reviewer_instructions)
async def main():
result = await run(
agent,
"def add(a, b): return a + b",
metadata={"language": "Python", "strictness": "strict"},
)
print(result.final_output)AgentInstructions
AgentInstructions = str | Callable[[dict], str | Awaitable[str]]The context dict passed to the callable:
{
"agent_name": agent.name,
"input": trimmed_prompt,
"purpose": purpose,
"metadata": merged_metadata,
}How agent messages are constructed
The SDK packs the agent's identity, instructions, context, and the user's prompt into a single user message with labelled sections:
Agent: code-reviewer
Instructions:
Review the following code.
Language: Python
...
Context:
Project: matilda-core
Code task:
def add(a, b): return a + bbuild_agent_chat_request(...)
Low-level async builder that constructs the chat request dict without executing it. Useful for testing, logging, or custom execution paths.
import asyncio
from matilda_agent_sdk import build_agent_chat_request
async def main():
request = await build_agent_chat_request(
prompt="Fix the failing test",
agent={"name": "helper", "purpose": "code"},
instructions="Be specific.",
context="Project root: /repo",
conversation_id="conv-1",
file_ids=["file-1"],
client_tools=[{"name": "read_file", "description": "Read a file", "parameters": {"type": "object"}}],
)
# request["messages"], request["responseMode"], request["conversation_id"], ...Parameters
| Field | type | description |
|---|---|---|
| prompt | str | The user's message. Required. |
| agent | Agent | dict | None | Optional agent to use. Defaults to a generic agent. |
| purpose | AgentPurpose | None | Fallback purpose if agent doesn't specify one. |
| instructions | AgentInstructions | None | Override the agent's instructions. |
| context | str | None | Override the agent's context. |
| metadata | dict | None | Merge with agent's metadata. |
| conversation_id | str | None | Associate with a conversation thread. |
| file_ids | list[str] | None | File IDs to attach. |
| client_tools | list[dict] | None | Client tools to advertise. |
| response_mode | str | None | Override response mode. |
| response_schema | str | None | Raw JSON Schema string to constrain output. |
| history | list[dict] | None | Prior-transcript messages replayed ahead of this turn. |
Returns a dict shaped like a chat request (messages, responseMode, optional conversation_id / fileIds / clientTools / responseSchema).