xtr_ai.bundle ¶
The container integration: one bundle, configured by :class:AiConfig.
AI_CHANNEL
module-attribute
¶
The log channel runs are logged on, when the logging bundle is active.
TOOL_TAG
module-attribute
¶
The tag on the toolset built from a class's @as_tool methods for one agent.
DEFAULT_STORE
module-attribute
¶
The conversation store also injected without a name.
CapabilityEntry ¶
A capability: pydantic-ai's declarative form ("Thinking", {"Thinking": {...}}), a
capability itself (Thinking(effort="low")), or a capability class the container builds, with
injection.
ConversationStoreEntry ¶
ConversationStoreEntry = InMemoryConversationStoreConfig | OrmConversationStoreConfig | ServiceConversationStoreConfig
What AiConfig.conversation_stores maps a name to.
AgentConfig
dataclass
¶
AgentConfig(platform: str, model: str, fallbacks: tuple[ModelRef, ...] = (), instructions: str | None = None, instructions_file: str | None = None, model_settings: Mapping[str, Any] = dict[str, Any](), retries: int | None = None, end_strategy: Literal['early', 'graceful', 'exhaustive'] = 'graceful', tool_timeout: float | None = None, metadata: Mapping[str, Any] = dict[str, Any](), deps_type: type[Any] = NoneType, output_type: Any = str, capabilities: tuple[CapabilityEntry, ...] = (), toolsets: tuple[ToolsetEntry, ...] = (), usage_limits: UsageLimits | None = None, timeout: float | None = None)
An agent: its model, its instructions, its capabilities and tools, and run defaults.
Attributes:
-
platform(str) –The platform its model runs on; may be
env("…")to choose per environment. -
model(str) –The model's name on that platform; may be
env("…")too. -
fallbacks(tuple[ModelRef, ...]) –Models tried in order when the model fails.
-
instructions(str | None) –The instructions, inline.
-
instructions_file(str | None) –A file holding them instead, read when the agent is first built.
%kernel.project_dir%may start the path. -
model_settings(Mapping[str, Any]) –pydantic-ai model settings for every run.
-
retries(int | None) –Tool and output retry budget.
-
end_strategy(Literal['early', 'graceful', 'exhaustive']) –pydantic-ai's end strategy.
-
tool_timeout(float | None) –Default timeout of a tool call, in seconds.
-
metadata(Mapping[str, Any]) –Stored with every run.
-
deps_type(type[Any]) –The type of the dependencies a run is given.
-
output_type(Any) –What a run returns.
-
capabilities(tuple[CapabilityEntry, ...]) –Capabilities: declarative, built already, or classes the container builds.
-
toolsets(tuple[ToolsetEntry, ...]) –Toolsets the container builds, and agents called as tools.
-
usage_limits(UsageLimits | None) –Default usage limits of a run; a call passing its own wins.
-
timeout(float | None) –Default timeout of a run, in seconds; a call passing its own wins.
AiBundle ¶
Registers each configured platform, agent and conversation store.
Nothing is built, imported from a provider's SDK or read from the
environment while the container builds or boots: an agent is built the
first time it is injected, and its platform the first time a run needs a
model. Agents are injected by name — Annotated[AbstractAgent,
Target("chat")] — and all of them as Mapping[Hashable, AbstractAgent].
Hold no mapping passes and no agents yet.
build ¶
Collect @as_tool methods, and ready the conversation tables when the orm is there.
prepend_extension ¶
Add the ai channel to the logging configuration, when logging is active.
load_extension ¶
Register what config names; build none of it.
Raises:
-
InvalidConfigurationError–When a literal reference names nothing configured, agents call each other in a cycle, or an orm adapter lacks its bridge package.
process ¶
Register what agents are built from, and give each the toolsets its tools make.
A capability, toolset or tool class the application registered itself is used as registered; any other is registered as a singleton.
Raises:
-
InvalidConfigurationError–When a tool names an agent that is not configured, or a capability, toolset or tool class is not a singleton — an agent is one, and outlives any scope.
AiConfig
dataclass
¶
AiConfig(platforms: Mapping[str, PlatformConfig] = dict[str, PlatformConfig](), agents: Mapping[str, AgentConfig] = dict[str, AgentConfig](), conversation_stores: Mapping[str, ConversationStoreEntry] = dict[str, ConversationStoreEntry]())
Named platforms, named agents and named conversation stores.
Empty by default: nothing is registered that is not configured, and nothing configured is built before it is first used.
Attributes:
-
platforms(Mapping[str, PlatformConfig]) –Each platform by name — the prefix of its model ids.
-
agents(Mapping[str, AgentConfig]) –Each agent by name — what it is injected by.
-
conversation_stores(Mapping[str, ConversationStoreEntry]) –Each conversation store by name;
"default"is also injected without a name.
InMemoryConversationStoreConfig
dataclass
¶
pydantic-ai's in-memory store: this process only, gone when it stops.
OrmConversationStoreConfig
dataclass
¶
ServiceConversationStoreConfig
dataclass
¶
A ConversationStore the application registers itself, under its class.
ModelRef
dataclass
¶
The model model of the platform platform: <platform>:<model>.
PlatformConfig
dataclass
¶
PlatformConfig(provider: str, api_key: str | None = None, base_url: str | None = None, options: Mapping[str, Any] = dict[str, Any](), model_settings: Mapping[str, Any] = dict[str, Any]())
A provider, its key, its endpoint and its other options, under one name.
Attributes:
-
provider(str) –Any provider name pydantic-ai knows (
openai,anthropic,azure,bedrock,google,ollama, …), ortest/functionfor pydantic-ai's in-process test models. -
api_key(str | None) –The key, usually
env("…"). Never shown in a report. -
base_url(str | None) –The endpoint, for an OpenAI-compatible server or a proxy.
-
options(Mapping[str, Any]) –The provider's other constructor keywords, passed unchanged —
api_version,region,project, …; fortest,TestModel's; forfunction,functionand/orstream_function. -
model_settings(Mapping[str, Any]) –Defaults every model of this platform carries, under the agent's and the run's —
timeout,max_tokens, …
Its repr names every option but shows none of their values, and masks
the credentials a base_url carries: an option can hold a key under any
name a provider gives it.
AgentToolRef
dataclass
¶
ToolsetRef
dataclass
¶
A toolset the container builds: a pydantic-ai AbstractToolset subclass, with injection.
The class is registered as a singleton unless the application registers it itself.