Agents

Overview

Agents are the primary interface for AI-powered interactions on Meibel. An agent combines three things: what to know (datasource bindings), how to think (system prompt and configuration), and what to produce (artifact schemas). When a user sends a message to an agent, the agent searches its bound datasources for relevant context, applies its system prompt to frame its reasoning, and generates a response. If an artifact schema is attached, the agent also produces structured output conforming to that schema. Agents are not stateless functions — they operate within sessions that maintain conversation history, and they follow a versioning model that gives you reproducibility and safe rollback.

Agent Configuration

An agent is defined by:

Name and description — human-readable identifiers for the agent
System prompt — instructions that define the agent’s behavior, tone, and constraints. This is the most important configuration: it tells the agent what role it plays and how it should respond.
Datasource bindings — which datasources the agent can search for context. An agent with no datasources has no domain knowledge; it can only use its base model capabilities. An agent with well-curated datasources can answer domain-specific questions accurately.
Artifact schemas — optional structured output definitions (see below)
Prompt templates — optional reusable prompt configurations

The system prompt is where you encode domain expertise. A well-written system prompt for a legal review agent might specify: “You are a contract analyst. When asked about a contract, cite specific clauses by section number. If a clause is ambiguous, flag it explicitly. Never fabricate clause numbers.”

Versioning

Agents follow a draft-publish workflow:

Create or edit a draft — make changes to the agent’s configuration, system prompt, or datasource bindings
Publish — freeze the current draft as an immutable version with a version number

Published versions are immutable. The same version number always produces the same behavior (given the same inputs and datasource state). This gives you:

Reproducibility — you can point to a specific version and know exactly how it was configured
Safe rollback — if a new version performs poorly, revert to a previous one
Audit trail — each version captures the full configuration at the time of publication

from meibel.models import PublishAgentDefinitionRequest

# Publish the current draft
version = client.agents.publish(
    agent_id="agent_abc123",
    body=PublishAgentDefinitionRequest(commit_message="Publish current draft"),
)
print(f"Published version: {version.version}")

# List all versions
versions = client.agents.list_versions(agent_id="agent_abc123")
for v in versions:
    print(f"  v{v.version}: published {v.created_at}")

Sessions

A session is a conversation container bound to an agent. When you create a session, you get a unique session ID that you use for all subsequent messages in that conversation. Sessions maintain message history, so the agent has conversational context. The third message in a session can reference something discussed in the first message — the agent sees the full history when generating each response.

# Create a session
session = client.agents.sessions.create(agent_id="agent_abc123")

# Send messages within the session
response = client.agents.sessions.send_chat_message(
    session_id=session.session_id,
    body=ChatMessageRequest(user_message="What are the payment terms in the contract?"),
)
print(response.assistant_response)

# Follow up — the agent remembers the previous exchange
response = client.agents.sessions.send_chat_message(
    session_id=session.session_id,
    body=ChatMessageRequest(user_message="Are there any penalties for late payment?"),
)

Sessions can also be listed and inspected after the fact, which is useful for auditing and debugging.

Chat

Agent chat supports two modes:

Synchronous
Streaming

Send a message and wait for the full response. Simple and straightforward — best for backend integrations where latency tolerance is higher.

from meibel.models import ChatMessageRequest

response = client.agents.sessions.send_chat_message(
    session_id=session.session_id,
    body=ChatMessageRequest(user_message="Summarize the key risks."),
)
print(response.assistant_response)
print(f"Tokens used: {response.token_usage}")

Receive response tokens as they are generated via Server-Sent Events (SSE). Best for user-facing interfaces where you want to display the response progressively.

stream = client.agents.sessions.send_chat_message_stream(
    session_id=session.session_id,
    body=ChatMessageRequest(user_message="Summarize the key risks."),
)
for event in stream:
    print(event, end="", flush=True)

Both modes return the same information — the assistant’s message, token usage, suggested actions, and tool activity. Streaming just delivers it incrementally.

Artifacts and Schemas

Agents can produce structured outputs defined by artifact schemas. An artifact schema specifies the JSON structure the agent should fill when generating a response. This is particularly useful for extraction tasks. Instead of asking an agent “what are the key terms in this contract?” and parsing the free-text response, you define a schema:

{
  "type": "object",
  "properties": {
    "effective_date": { "type": "string", "description": "Contract effective date" },
    "termination_date": { "type": "string", "description": "Contract end date" },
    "total_value": { "type": "number", "description": "Total contract value" },
    "key_obligations": {
      "type": "array",
      "items": { "type": "string" },
      "description": "List of key obligations"
    }
  }
}

The agent fills this schema from the document context, giving you structured data you can store, compare, or feed into downstream systems without parsing natural language. Artifact schemas are managed independently from agents — you create a schema once and attach it to any agent that needs it.

Prompt Templates

Prompt templates are reusable prompt configurations that can be attached to agents. They are useful when multiple agents need similar instructions — for example, a set of agents that all need to follow the same citation format, or a common preamble about your organization’s policies. Instead of duplicating the same text across multiple agent system prompts, define it once as a template and reference it. When you update the template, all agents using it pick up the change.

# List available prompt templates
templates = client.prompts.list_prompts()
for t in templates.data:
    print(f"  {t.name}: {t.prompt_id}")

Observability

Understanding how an agent arrived at its response is critical for debugging, quality assurance, and building trust in AI outputs. Meibel provides several layers of observability: Session message history — the full conversation log for any session. You can review exactly what the user asked and what the agent responded, including intermediate exchanges. Token usage — every response includes token counts, so you can track cost and monitor for unexpectedly long responses that might indicate the agent is struggling. Tool activity — when an agent uses tools (searching datasources, running retrievals), the tool activity log shows what it did and why. This tells you which datasources were searched, what queries were used, and what results came back. Trace events — for document processing operations, trace events provide a step-by-step record of the processing pipeline. You can see how a document was parsed, what structures were detected, and how data elements were extracted.

Include include_tool_activity=True in your chat request to get tool activity logs alongside the response. This is the fastest way to debug cases where the agent gives an unexpected answer — check what context it actually retrieved.

response = client.agents.sessions.send_chat_message(
    session_id=session.session_id,
    body=ChatMessageRequest(
        user_message="What is the contract value?",
        include_tool_activity=True,
    ),
)

# Inspect what the agent did
print(f"Answer: {response.assistant_response}")
print(f"Tokens: {response.token_usage}")
if response.tool_activity:
    for activity in response.tool_activity:
        print(f"  Tool: {activity}")

Get started

Tutorials

Core concepts

Agents and sessions

Data and documents

Operations

Document parsing reference

Support

Overview

Agent Configuration

Versioning

Sessions

Chat

Artifacts and Schemas

Prompt Templates

Observability

​Overview

​Agent Configuration

​Versioning

​Sessions

​Chat

​Artifacts and Schemas

​Prompt Templates

​Observability

Overview

Agent Configuration

Versioning

Sessions

Chat

Artifacts and Schemas

Prompt Templates

Observability