# 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](https://docs.agno.com/agents/overview), [teams](https://docs.agno.com/teams/overview), [workflows](https://docs.agno.com/workflows/overview), [sessions](https://docs.agno.com/sessions/overview), [memory](https://docs.agno.com/memory/overview), and [human-in-the-loop](https://docs.agno.com/hitl/overview).
- Pydantic AI: [agents](https://pydantic.dev/docs/ai/core-concepts/agent/), [message history](https://pydantic.dev/docs/ai/core-concepts/message-history/), [hooks](https://pydantic.dev/docs/ai/core-concepts/hooks/), [graphs](https://pydantic.dev/docs/ai/graph/graph/), and [deferred tools](https://pydantic.dev/docs/ai/tools-toolsets/deferred-tools/).
- Pydantic AI Harness: [overview](https://pydantic.dev/docs/ai/harness/), [memory](https://pydantic.dev/docs/ai/harness/memory/), [guardrails](https://pydantic.dev/docs/ai/harness/guardrails/), [skills](https://pydantic.dev/docs/ai/harness/skills/), [subagents](https://pydantic.dev/docs/ai/harness/subagents/), and [step persistence](https://pydantic.dev/docs/ai/harness/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. |