jazz-agent

AgentCall — a Python wrapper around the Anthropic SDK that provides structured Claude calls with an MCP tool loop and a shared notes side channel for inter-agent communication.

What it is

jazz-agent gives you a single class, AgentCall, that:

- Runs a Claude model call with full tool-loop support (calls MCP services until end_turn) - Reads/writes a shared notes side channel so multiple agents can communicate without direct memory passing - Returns a structured AgentResult with the final text, all tool calls made, usage stats, and session ID

Quick start

from agent.agent_call import AgentCall

result = AgentCall(
    system="You are a concise code reviewer.",
    prompt="Review this function: def add(a, b): return a - b",
).run()

print(result.text)

AgentCall parameters

| Parameter | Type | Default | Description | |---|---|---|---| | system | str | required | System prompt | | prompt | str | required | User message / task | | model | str | "claude-opus-4-8" | Claude model ID | | mcp_services | list[str] | [] | MCP service names to load tools from | | url_overrides | dict[str, str] | {} | Override default MCP service URLs | | tools | list[dict] | [] | Raw Claude-format tool schemas (merged with MCP tools) | | max_tokens | int | 4096 | Max output tokens | | thinking | bool | True | Enable adaptive thinking | | streaming | bool | True | Use streaming API | | api_key | str | env ANTHROPIC_API_KEY | Anthropic API key | | read_shared | bool | False | Prepend shared notes from side channel to context | | write_shared | str | None | If set, write result summary as a shared note with this title | | session_id | str | auto (8 hex chars) | Trace ID for the call | | collection | str | "jazz-dev" | Notes collection for the shared side channel |

AgentResult fields

| Field | Type | Description | |---|---|---| | text | str | Final text response | | tool_calls | list[dict] | All tool calls made during the loop | | stop_reason | str | Claude stop reason (end_turn, max_tokens, etc.) | | model | str | Model used | | usage | dict | {"input_tokens": N, "output_tokens": N} | | shared_notes | list[dict] | Notes written to shared side channel this run | | session_id | str | Session trace ID |

result.ok() returns True when stop_reason is end_turn or tool_use and there is text or tool output.

Shared notes side channel

Agents communicate by writing notes tagged "shared" to a central notes DB (default: http://localhost:8001).

from agent.agent_call import read_shared_notes, write_shared_note

# Write a note visible to all agents
write_shared_note(title="Summary", body="Task complete", extra_tags=["agent:worker"])

# Read all shared notes
notes = read_shared_notes(collection="jazz-dev")

Set NOTES_DB_URL in the environment to point at your notes service.

Use read_shared=True on AgentCall to automatically prepend current shared notes to the context, or write_shared="My note title" to automatically publish the result.

MCP services

Register MCP services by name:

result = AgentCall(
    system="You have access to the notes database.",
    prompt="Summarize all notes tagged 'shared'.",
    mcp_services=["notes_db_mcp", "z3_mcp"],
).run()

Default URLs are read from environment variables (NOTES_DB_MCP_URL, Z3_MCP_URL, COUPLER_URL) or override per-call with url_overrides.

Install

pip install jazz-agent --index-url https://gitlab.com/api/v4/projects/83824314/packages/pypi

Or for development:

pip install -e ".[test]"
python -m pytest tests/ -v