index

Agent is a reusable, typed Junjo executable for the case where a model chooses the next capability at runtime. It is a sibling of Workflow. An Agent has no fabricated Graph, and a Tool is an operation rather than a Node.

The definition declares all behavior-affecting structure up front:

• a stable application-owned key and display name;
• exact instructions and typed input/output boundaries;
• one provider-neutral ModelDriverBinding;
• an ordered collection of explicitly typed Tool definitions;
• positive model-request and Tool-call limits.

Every execute call creates a fresh run identity, private Store, transcript, counters, usage aggregate, lifecycle snapshot, and per-run collaborator cache. The caller owns request dependencies, history selection, persistence, provider credentials, transactions, and product transport.

Minimal definition

The core package deliberately owns no provider SDK. A ModelDriver translates one immutable normalized ModelRequest into either FinalOutputResponse or ToolCallsResponse.

from pydantic import BaseModel

from junjo import (
    Agent,
    AgentLimits,
    ModelDriverBinding,
    ModelDriverDescriptor,
)
from junjo.agent import FinalOutputResponse
from junjo.agent.testing import ScriptedModelDriver

class Question(BaseModel):
    text: str

class Answer(BaseModel):
    text: str

driver = ScriptedModelDriver([
    FinalOutputResponse(output={"text": "deterministic answer"})
])

agent = Agent(
    key="answer_question",
    name="Answer Question",
    instructions="Answer using available evidence.",
    input_type=Question,
    model=ModelDriverBinding.shared(
        descriptor=ModelDriverDescriptor(
            driver_key="scripted",
            provider="junjo",
            model="scripted-v1",
            fixture=True,
        ),
        driver=driver,
    ),
    tools=[],
    output_type=Answer,
    limits=AgentLimits(model_requests=4, tool_calls=8),
)

result = await agent.execute(
    Question(text="What happened?"),
    dependencies=None,
)

The successful result always contains validated output, a detached normalized transcript, usage evidence, identities, counters, and terminal reason. Failure raises a typed AgentError; there is no output-less success result.