Skip to content

Agent

The Agent facade is the primary entry point for interacting with Cognitia.

Agent

Agent

High-level facade for interacting with the AI agent.

Supports: - query(prompt) → Result (one-shot) - stream(prompt) → AsyncIterator[StreamEvent] (streaming) - conversation() → Conversation (multi-turn)

runtime_factory property 

runtime_factory: RuntimeFactoryPort

Application-facing runtime factory seam.

runtime_capabilities property 

runtime_capabilities: Any

Capability descriptor for the selected runtime for app-level introspection.

query async 

query(prompt: str, *, messages: list[Message] | None = None) -> Result

One-shot request -> Result.

Parameters:

Name Type Description Default
prompt str

The user prompt (appended as the final user message).

 required
messages list[Message] | None

Optional conversation history to prepend before the current prompt. Each message is a Message(role, content, ...). If None or empty, behaves as a standalone one-shot query.

 None

query_structured async 

query_structured(prompt: str, output_type: type[T], *, max_retries: int | None = None) -> T

One-shot request returning a validated Pydantic model.

Creates a temporary AgentConfig with output_type set, runs query(), and returns the validated structured_output.

Parameters:

Name Type Description Default
prompt str

The user prompt.

 required
output_type type[T]

A Pydantic BaseModel subclass. The LLM response is parsed and validated against this type. Retry on validation error.

 required
max_retries int | None

Override max_model_retries for structured output validation. Default: uses the runtime's default (2).

 None

Returns:

Type Description
T

A validated instance of output_type.

Raises:

Type Description
StructuredOutputError

If all retries are exhausted and validation still fails.

conversation 

conversation(session_id: str | None = None) -> Any

Create a multi-turn Conversation.

cleanup async 

cleanup() -> None

Release resources (runtime, adapter, subprocess).

AgentConfig

AgentConfig dataclass

Immutable configuration for the Agent facade.

The only required parameter is system_prompt. All others have sensible defaults.

resolved_model property 

resolved_model: str

Deprecated compatibility wrapper for model alias resolution.

Result

Result dataclass

Immutable result of a query/stream request.

ok=True if error is None (request succeeded).

ok property 

ok: bool

True if the request completed without error.

StructuredOutputError

StructuredOutputError

Bases: Exception

Raised when structured output validation fails after all retries.

Attributes:

Name Type Description
raw_text

The raw LLM response text that failed validation.
output_type_name

Name of the expected Pydantic model type.