Agent

#Public Facade

daita.Agent is the public facade for one persistent agent. It validates caller input and delegates composition, locking, catalog work, capability execution, artifacts, jobs, routines, and persistence to the embedded runtime.

Every run() starts one bounded transcript-driven loop and returns one terminal LoopExit. A conversation provides bounded continuity across completed runs; it is not a resumable loop or session runtime.

#Local Lifecycle

Local composition requires one explicit workspace on every create or open:

python

from pathlib import Path
 
from daita import Agent, LocalWorkspace
 
workspace = LocalWorkspace(Path("/absolute/path/project"))
 
agent = await Agent.create("atlas", workspace=workspace)
await agent.close()
 
agent = await Agent.open("atlas", workspace=workspace)
await agent.close()

The workspace and Daita state root must not overlap. The filesystem root, the user's home directory, missing directories, and non-directories are rejected.

Use an alternate state root for isolated applications or tests:

python

agent = await Agent.create(
    "atlas",
    workspace=workspace,
    root="/absolute/path/daita-state",
)

List and delete inactive agents with class methods:

python

names = await Agent.list(root="/absolute/path/daita-state")
await Agent.delete("atlas", root="/absolute/path/daita-state")

Deletion removes the agent home and Daita-owned keychain credentials. It never modifies an attached database or a user-owned artifact copy.

#Configure a Model

The terminal is the recommended model-onboarding path. Python callers can validate and persist one route:

python

import os
 
agent = await Agent.create("atlas", workspace=workspace)
try:
    await agent.configure_model(
        provider="openai",
        model="gpt-5.6-terra",
        api_key=os.environ["OPENAI_API_KEY"],
    )
finally:
    await agent.close()
 
# The persisted route is admitted on the next open.
agent = await Agent.open("atlas", workspace=workspace)

Unknown or custom model identities require explicit context_window_tokens and max_output_tokens. Subscription routes have separate authentication requirements; see LLM Providers.

#Run

python

result = await agent.run("Summarize revenue by region")

The main run selectors are:

python

result = await agent.run(
    "Compare this month with last month",
    conversation_id="conversation-id",
    source_id="source-id",
    files_only=False,
)

conversation_id continues a bounded projection of completed prior runs.
source_id scopes a new conversation to one attached source.
files_only=True omits attached source, MCP, and source-job tools for that run.

The returned LoopExit includes:

Field	Meaning
`run_id`	Persistent identifier for this run
`conversation_id`	Conversation grouping used by the run
`kind`	`completed`, `failed`, or `interrupted`
`reason`	Stable terminal reason
`final_text`	Final model text when completed
`steps`	Completed outer loop steps
`usage`	Aggregated provider-neutral tokens and estimated cost
`artifacts`	Verified artifact references committed by the run
`artifact_deliveries`	Local artifact-delivery receipts when present

#Inspect Durable State

python

transcript = await agent.transcript(result.run_id)
runs = await agent.conversation_runs(result.conversation_id)
exists = await agent.conversation_exists(result.conversation_id)
 
jobs = await agent.list_jobs()
routines = await agent.list_routines()
deliveries = await agent.inbox(conversation_id=result.conversation_id)

A transcript contains the exact user, assistant, and tool messages from one run. Prior conversation context may be projected into a later model request, but it is never copied into the later run's transcript.

Known artifact IDs can be recovered without rerunning the model:

python

payload = await agent.read_artifact(artifact_id)
receipt = await agent.save_artifact(artifact_id)

See Artifacts, Durable Jobs, Scheduled Routines, and Inbox and Deliveries for their lifecycle contracts.

#Source and Integration Management

python

sources = await agent.list_sources()
active = await agent.active_source()
selected = await agent.select_source("Sales")
refreshed = await agent.refresh_source(selected.id)
 
mcp_bindings = await agent.list_mcp_servers()
permissions = await agent.inspect_source_permissions(selected.id)

Source attachment, permission previews, MCP admission, memory, semantics, skills, and candidate review are explicit public operations covered in their dedicated guides.

#Close Reliably

python

agent = await Agent.open("atlas", workspace=workspace)
try:
    result = await agent.run("Summarize orders")
finally:
    await agent.close()

or:

python

async with await Agent.open("atlas", workspace=workspace) as agent:
    result = await agent.run("Summarize orders")

Closing releases the process writer lock, waits for owned in-flight work to settle, and closes supervisors and initialized integrations. It does not delete persistent state. A TUI, CLI process, and resident host cannot open the same agent home concurrently.