references/RESEARCH-AND-MAPPING.md
references/RESEARCH-AND-MAPPING.mdBrowse 4 files
1,986 tokens
9,351 bytes
Token encoding: o200k_base
Snapshot 9e9fdc4
← Back to SKILL.md
Research and concept mapping
Use this reference conditionally after tracing the source path. It is a decision guide, not a requirement to reproduce the entire Agno platform.
Primary documentation
Inspect installed versions before migrating because Agno, Pydantic AI, and Harness continue to evolve.
- Agno: agents, teams, workflows, sessions, memory, and human-in-the-loop.
- Pydantic AI: agents, message history, hooks, graphs, and deferred tools.
- Pydantic AI Harness: overview, memory, guardrails, skills, subagents, and step persistence.
Ownership map
| Observed Agno behavior | Target owner and likely seam | Focused proof |
|---|---|---|
Agent.run() / arun() and RunOutput.content, messages, metrics, or references | Core: Agent.run() / run_sync(), AgentRunResult; Application: response adapter | Assert caller-visible output, required trajectory fields, usage, errors, and side effects. |
stream=True, stream_events=True, background streaming, or resumed event streams | Core: run_stream(), run_stream_events(), event_stream_handler, or iter(); Application: event/cursor adapter | Assert reconstruction, order, stable fields, terminal detection, cancellation, reconnect/resume behavior, and no duplicate output. |
| Instructions, model, retries, reasoning, and call options | Core: instructions, model/provider settings, retries, and UsageLimits; Application: configuration mapping | Construct every configured branch and assert limits/defaults actually consumed by the slice. |
dependencies, RunContext, user_id, session_id, and metadata interpolation | Core: typed deps_type, RunContext.deps, dynamic instructions/tool preparation; Application: authenticated context construction | Inspect tool schemas and prove identity, credentials, stores, and services cannot be model-selected. |
Functions, Function, Toolkit, MCP tools, and tool-choice restrictions | Core: typed tools, Tool, function toolsets, MCPToolset, preparation capabilities | Assert names, schemas, return shape, error/retry behavior, timeout, concurrency, and effects. |
output_schema, output_model, parser, or second structuring model | Core: Pydantic output type and explicit NativeOutput, ToolOutput, PromptedOutput, or TextOutput where transport matters | Assert valid output, invalid-output retries/errors, and preserve any second-model pass explicitly. |
| Pre-hooks, post-hooks, and tool hooks | Core: Hooks, custom capability hooks, output validators, or toolset wrappers; Harness: ToolGuardrail when a tool-hook policy matches; Application: public error/event adapter | Golden-test firing point, input mutation, short-circuit, order, retries, exceptions, persistence, and streaming visibility. |
| Input/output guardrails | Harness: matching InputGuardrail or OutputGuardrail; Core: output validators or custom capability when lifecycle differs | Exercise allow, block, replace/redact, retry, parallel execution, and caller-visible error/event shape. |
| Database-backed session messages and summaries | Core: normalized messages; Application: existing store, ownership, retention, summary policy, and record migration | Continue in a fresh process, test incomplete tool calls and store errors, and reject cross-user/session access. |
session_state, agentic state tools, or state interpolation | Application/Graph: typed state store; Core: dependencies provide trusted access, tools expose only intended mutations | Assert merge/overwrite policy, concurrent writes, namespace, prompt injection, and restart independently of messages. |
| User memories and learning | Harness: Memory only when a model-owned namespaced notebook fits; otherwise Application: retain the memory/learning service | Assert write trigger, schema, retrieval/injection, update/delete policy, tenant scope, bounds, and fresh-process continuation. |
| Knowledge bases, readers, embedders, vector DBs, filters, and references | Application: existing retrieval service behind dependencies or a tool; Core: tool call and result | Assert ingestion separately from query ranking, filters, citation shape, tenancy, failure behavior, and freshness. |
| Session summary, history window, compression | Core/Harness: history processing or an observed matching compaction strategy; Application: persisted summary contract | Assert exactly what context survives, when summary runs, failure fallback, cost, and continuation. Do not equate generic compaction with memory. |
Team delegation to members | Harness: SubAgents for isolated model-directed tasks; Core: agent-as-tool or programmatic delegation; Application/Graph: other collaboration modes | Assert member selection, input/history isolation, shared context, result handback, aggregation, events, budgets, cancellation, and recursion. |
| Team coordinate/route/broadcast/tasks modes | Application/Graph unless a focused Harness composition proves the observed semantics | Assert routing, fan-out concurrency, merge order, leader/member retries, partial failure, and public result/event shape. |
| Fixed sequential workflow | Application: plain typed async functions; Graph: pydantic_graph when graph inspection adds value | Assert step inputs/outputs, order, error propagation, and terminal status. |
| Conditions, routers, loops, parallel steps, and custom workflow functions | Application/Graph: explicit Python control flow and typed graph state | Assert chosen route, loop stop, join shape, source ordering, concurrency limit, cancellation, and partial failure. |
| Workflow session state, pause/resume, checkpoints, and persisted steps | Application or durable engine: workflow state and progress; Core durable integration: agent operations inside that workflow | Kill and restart at each promised boundary; validate resume payload, step identity, lineage, and idempotent effects. Graph state alone is not persistence. |
| Tool confirmation | Core: requires_approval, ApprovalRequired, or ApprovalRequiredToolset; inline HandleDeferredToolCalls or later DeferredToolResults; Application: policy, UI, audit, persistence | Exercise deny/approve and prove zero effects before or after denial and exactly one after approval. |
| User-input pauses | Application: collect and validate conversational input; resume with explicit message or application state | Assert prompt/request shape, timeout/cancel, correlation, duplicate input, restart, and how input enters model context. |
| External tool execution | Application: execute the pending validated request; Core: deferred result resumes the agent | Persist the complete request, authorize executor, assert result/error mapping and exactly-once effect policy. |
| Agno Skills | Harness: Skills for SKILL.md instructions; FileSystem, Shell, or Application tools for observed resources/scripts | Assert configured discovery, on-demand selection, every required reference/resource, trust, and script permissions separately. |
| AgentOS API, auth, sessions, control plane, registry, config, telemetry, and deployment | Application/infrastructure | Exercise retained routes/jobs including auth, tenancy, wire shape, scaling, and failures. |
| AgentOS interfaces such as AG-UI, A2A, Slack, or WhatsApp | Core UI adapters where protocol fits; Application: transport and auth | Run protocol fixtures or end-to-end tests; do not infer parity from having another UI adapter. |
| Evals, cases/suites, judges, and metrics | Evals (pydantic_evals): cases, datasets, evaluators; Application: scheduling and score storage | Add the separate dependency, compare essential metrics on the same cases, and separately prove live sampling/persistence. |
| OpenTelemetry and Agno tracing | Core: instrumentation/OpenTelemetry; optional Logfire; Application: existing backend and adapters | Assert trace correlation, content/privacy policy, required spans, retention, dashboards, and alerts before switching. |
| File, shell, browser, code execution, or broad Agno toolkit catalog | Harness: matching focused capabilities such as Coder, FileSystem, Shell, browser capabilities, or ModalSandbox; Application: retained integrations | Assert only tools the slice uses, plus workspace effects, timeouts, output limits, credentials, and real containment when required. |