# aws-solutions-library-samples/guidance-for-agentic-ai-research-platform-on-aws architecture

> Architecture diagram of the GitHub repository aws-solutions-library-samples/guidance-for-agentic-ai-research-platform-on-aws, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aws-solutions-library-samples/guidance-for-agentic-ai-research-platform-on-aws
- Repository: https://github.com/aws-solutions-library-samples/guidance-for-agentic-ai-research-platform-on-aws

## Overview

AI Research Platform is a browser-based research assistant with configurable agents, project and task management, and streamed responses. A user submits a research prompt; the platform routes execution to an AgentCore agent, which can use research and sandbox tools, while project/task state and conversations are persisted. The graph also includes the documented custom-agent, team, and knowledge-retrieval capabilities. README and sampled files support the product shape; some runtime wiring and unsampled feature internals are omitted where their callers are not evidenced.

Main entry points: [`app/platform/src/server/router.ts`](https://github.com/aws-solutions-library-samples/guidance-for-agentic-ai-research-platform-on-aws/blob/main/app/platform/src/server/router.ts) (Service router), [`app/agents/base/agent.py`](https://github.com/aws-solutions-library-samples/guidance-for-agentic-ai-research-platform-on-aws/blob/main/app/agents/base/agent.py) (Base agent), [`lib/platform/agent-base-runtime.ts`](https://github.com/aws-solutions-library-samples/guidance-for-agentic-ai-research-platform-on-aws/blob/main/lib/platform/agent-base-runtime.ts) (Bedrock AgentCore), [`app/platform/src/app/(main)/thread/[id]/page.tsx`](https://github.com/aws-solutions-library-samples/guidance-for-agentic-ai-research-platform-on-aws/blob/main/app/platform/src/app/(main)/thread/%5Bid%5D/page.tsx) (Research chat)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Web experience"]
  node_thread_ui["Research chat<br/>[page.tsx]"]
  node_stream_hook["Chat streaming"]
  node_agent_ui["Agent setup<br/>[page.tsx]"]
  node_team_ui["Team setup<br/>[page.tsx]"]
end

subgraph group_services["Platform services"]
  node_rpc_route["RPC endpoint<br/>[route.ts]"]
  node_api_route["API endpoint<br/>[route.ts]"]
  node_router["Service router<br/>[router.ts]"]
  node_execute["Execution routes<br/>[execute.ts]"]
  node_thread_routes["Thread routes<br/>[thread.ts]"]
  node_agent_routes["Agent routes<br/>[agents.ts]"]
  node_team_routes["Team routes<br/>[teams.ts]"]
end

subgraph group_agents["Agent runtime"]
  node_base_agent["Base agent<br/>[agent.py]"]
  node_orchestrator["Orchestrator<br/>[agent.py]"]
  node_agent_tools["Research tools<br/>[retrieve.py]"]
  node_web_search["Web search<br/>[web_search.py]"]
  node_sandbox["Code sandbox"]
  node_task_tools["Task tools<br/>[tasks.py]"]
  node_base_task_tools["Task completion<br/>[tasks.py]"]
  node_db_helpers["Agent database access<br/>[db.py]"]
end

subgraph group_cloud["AWS services"]
  node_postgres[("PostgreSQL<br/>[database-stack.ts]")]
  node_agentcore["Bedrock AgentCore"]
  node_knowledge[("Knowledge base")]
end

node_user(("Researcher"))
node_web(("Web sources"))

node_user -->|"asks research"| node_thread_ui
node_thread_ui -->|"submits prompt"| node_stream_hook
node_stream_hook -->|"calls execution"| node_rpc_route
node_rpc_route -->|"dispatches RPC"| node_router
node_api_route -->|"dispatches API"| node_router
node_router -->|"routes execution"| node_execute
node_router -->|"routes threads"| node_thread_routes
node_router -->|"routes agents"| node_agent_routes
node_router -->|"routes teams"| node_team_routes
node_execute -->|"starts agent runtime"| node_agentcore
node_agentcore -->|"runs base agent"| node_base_agent
node_agentcore -->|"runs orchestrator"| node_orchestrator
node_base_agent -->|"uses retrieval"| node_agent_tools
node_base_agent -->|"searches web"| node_web_search
node_base_agent -->|"runs code"| node_sandbox
node_orchestrator -->|"manages tasks"| node_task_tools
node_base_agent -->|"marks task complete"| node_base_task_tools
node_task_tools -->|"accesses database"| node_db_helpers
node_db_helpers -->|"reads and writes"| node_postgres
node_agent_tools -.->|"retrieves knowledge"| node_knowledge
node_web_search -.->|"searches"| node_web
node_agent_ui -->|"configures agents"| node_agent_routes
node_team_ui -->|"configures teams"| node_team_routes

click node_thread_ui "https://github.com/aws-solutions-library-samples/guidance-for-agentic-ai-research-platform-on-aws/blob/main/app/platform/src/app/(main)/thread/%5Bid%5D/page.tsx"
click node_stream_hook "https://github.com/aws-solutions-library-samples/guidance-for-agentic-ai-research-platform-on-aws/blob/main/app/platform/src/hooks/use-chat-orchestrator-stream.ts"
click node_agent_ui "https://github.com/aws-solutions-library-samples/guidance-for-agentic-ai-research-platform-on-aws/blob/main/app/platform/src/app/(main)/agents/create/page.tsx"
click node_team_ui "https://github.com/aws-solutions-library-samples/guidance-for-agentic-ai-research-platform-on-aws/blob/main/app/platform/src/app/(main)/teams/create/page.tsx"
click node_rpc_route "https://github.com/aws-solutions-library-samples/guidance-for-agentic-ai-research-platform-on-aws/blob/main/app/platform/src/app/rpc/%5B%5B...rest%5D%5D/route.ts"
click node_api_route "https://github.com/aws-solutions-library-samples/guidance-for-agentic-ai-research-platform-on-aws/blob/main/app/platform/src/app/api/%5B%5B...rest%5D%5D/route.ts"
click node_router "https://github.com/aws-solutions-library-samples/guidance-for-agentic-ai-research-platform-on-aws/blob/main/app/platform/src/server/router.ts"
click node_execute "https://github.com/aws-solutions-library-samples/guidance-for-agentic-ai-research-platform-on-aws/blob/main/app/platform/src/server/routes/execute.ts"
click node_thread_routes "https://github.com/aws-solutions-library-samples/guidance-for-agentic-ai-research-platform-on-aws/blob/main/app/platform/src/server/routes/thread.ts"
click node_agent_routes "https://github.com/aws-solutions-library-samples/guidance-for-agentic-ai-research-platform-on-aws/blob/main/app/platform/src/server/routes/agents.ts"
click node_team_routes "https://github.com/aws-solutions-library-samples/guidance-for-agentic-ai-research-platform-on-aws/blob/main/app/platform/src/server/routes/teams.ts"
click node_base_agent "https://github.com/aws-solutions-library-samples/guidance-for-agentic-ai-research-platform-on-aws/blob/main/app/agents/base/agent.py"
click node_orchestrator "https://github.com/aws-solutions-library-samples/guidance-for-agentic-ai-research-platform-on-aws/blob/main/app/agents/orchestrator/agent.py"
click node_agent_tools "https://github.com/aws-solutions-library-samples/guidance-for-agentic-ai-research-platform-on-aws/blob/main/app/agents/base/tools/retrieve.py"
click node_web_search "https://github.com/aws-solutions-library-samples/guidance-for-agentic-ai-research-platform-on-aws/blob/main/app/agents/base/tools/web_search.py"
click node_sandbox "https://github.com/aws-solutions-library-samples/guidance-for-agentic-ai-research-platform-on-aws/blob/main/app/agents/base/tools/sandbox/agentcore_code_interpreter.py"
click node_task_tools "https://github.com/aws-solutions-library-samples/guidance-for-agentic-ai-research-platform-on-aws/blob/main/app/agents/orchestrator/tools/tasks.py"
click node_base_task_tools "https://github.com/aws-solutions-library-samples/guidance-for-agentic-ai-research-platform-on-aws/blob/main/app/agents/base/tools/tasks.py"
click node_db_helpers "https://github.com/aws-solutions-library-samples/guidance-for-agentic-ai-research-platform-on-aws/blob/main/app/agents/orchestrator/utils/db.py"
click node_postgres "https://github.com/aws-solutions-library-samples/guidance-for-agentic-ai-research-platform-on-aws/blob/main/lib/platform/database-stack.ts"
click node_agentcore "https://github.com/aws-solutions-library-samples/guidance-for-agentic-ai-research-platform-on-aws/blob/main/lib/platform/agent-base-runtime.ts"
click node_knowledge "https://github.com/aws-solutions-library-samples/guidance-for-agentic-ai-research-platform-on-aws/blob/main/lib/platform/knowledge-store-stack.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_thread_ui,node_stream_hook,node_agent_ui,node_team_ui toneBlue
class node_rpc_route,node_api_route,node_router,node_execute,node_thread_routes,node_agent_routes,node_team_routes toneAmber
class node_base_agent,node_orchestrator,node_agent_tools,node_web_search,node_sandbox,node_task_tools,node_base_task_tools,node_db_helpers toneMint
class node_postgres,node_agentcore,node_knowledge toneRose
class node_user,node_web toneIndigo
```

## Components

### Web experience

- [Research chat](https://github.com/aws-solutions-library-samples/guidance-for-agentic-ai-research-platform-on-aws/blob/main/app/platform/src/app/(main)/thread/%5Bid%5D/page.tsx): `app/platform/src/app/(main)/thread/[id]/page.tsx`
- [Chat streaming](https://github.com/aws-solutions-library-samples/guidance-for-agentic-ai-research-platform-on-aws/blob/main/app/platform/src/hooks/use-chat-orchestrator-stream.ts): `app/platform/src/hooks/use-chat-orchestrator-stream.ts`
- [Agent setup](https://github.com/aws-solutions-library-samples/guidance-for-agentic-ai-research-platform-on-aws/blob/main/app/platform/src/app/(main)/agents/create/page.tsx): `app/platform/src/app/(main)/agents/create/page.tsx`
- [Team setup](https://github.com/aws-solutions-library-samples/guidance-for-agentic-ai-research-platform-on-aws/blob/main/app/platform/src/app/(main)/teams/create/page.tsx): `app/platform/src/app/(main)/teams/create/page.tsx`

### Platform services

- [RPC endpoint](https://github.com/aws-solutions-library-samples/guidance-for-agentic-ai-research-platform-on-aws/blob/main/app/platform/src/app/rpc/%5B%5B...rest%5D%5D/route.ts): `app/platform/src/app/rpc/[[...rest]]/route.ts`
- [API endpoint](https://github.com/aws-solutions-library-samples/guidance-for-agentic-ai-research-platform-on-aws/blob/main/app/platform/src/app/api/%5B%5B...rest%5D%5D/route.ts): `app/platform/src/app/api/[[...rest]]/route.ts`
- [Service router](https://github.com/aws-solutions-library-samples/guidance-for-agentic-ai-research-platform-on-aws/blob/main/app/platform/src/server/router.ts): `app/platform/src/server/router.ts`
- [Execution routes](https://github.com/aws-solutions-library-samples/guidance-for-agentic-ai-research-platform-on-aws/blob/main/app/platform/src/server/routes/execute.ts): `app/platform/src/server/routes/execute.ts`
- [Thread routes](https://github.com/aws-solutions-library-samples/guidance-for-agentic-ai-research-platform-on-aws/blob/main/app/platform/src/server/routes/thread.ts): `app/platform/src/server/routes/thread.ts`
- [Agent routes](https://github.com/aws-solutions-library-samples/guidance-for-agentic-ai-research-platform-on-aws/blob/main/app/platform/src/server/routes/agents.ts): `app/platform/src/server/routes/agents.ts`
- [Team routes](https://github.com/aws-solutions-library-samples/guidance-for-agentic-ai-research-platform-on-aws/blob/main/app/platform/src/server/routes/teams.ts): `app/platform/src/server/routes/teams.ts`

### Agent runtime

- [Base agent](https://github.com/aws-solutions-library-samples/guidance-for-agentic-ai-research-platform-on-aws/blob/main/app/agents/base/agent.py): `app/agents/base/agent.py`
- [Orchestrator](https://github.com/aws-solutions-library-samples/guidance-for-agentic-ai-research-platform-on-aws/blob/main/app/agents/orchestrator/agent.py): `app/agents/orchestrator/agent.py`
- [Research tools](https://github.com/aws-solutions-library-samples/guidance-for-agentic-ai-research-platform-on-aws/blob/main/app/agents/base/tools/retrieve.py): `app/agents/base/tools/retrieve.py`
- [Web search](https://github.com/aws-solutions-library-samples/guidance-for-agentic-ai-research-platform-on-aws/blob/main/app/agents/base/tools/web_search.py): `app/agents/base/tools/web_search.py`
- [Code sandbox](https://github.com/aws-solutions-library-samples/guidance-for-agentic-ai-research-platform-on-aws/blob/main/app/agents/base/tools/sandbox/agentcore_code_interpreter.py): `app/agents/base/tools/sandbox/agentcore_code_interpreter.py`
- [Task tools](https://github.com/aws-solutions-library-samples/guidance-for-agentic-ai-research-platform-on-aws/blob/main/app/agents/orchestrator/tools/tasks.py): `app/agents/orchestrator/tools/tasks.py`
- [Task completion](https://github.com/aws-solutions-library-samples/guidance-for-agentic-ai-research-platform-on-aws/blob/main/app/agents/base/tools/tasks.py): `app/agents/base/tools/tasks.py`
- [Agent database access](https://github.com/aws-solutions-library-samples/guidance-for-agentic-ai-research-platform-on-aws/blob/main/app/agents/orchestrator/utils/db.py): `app/agents/orchestrator/utils/db.py`

### AWS services

- [PostgreSQL](https://github.com/aws-solutions-library-samples/guidance-for-agentic-ai-research-platform-on-aws/blob/main/lib/platform/database-stack.ts): `lib/platform/database-stack.ts`
- [Bedrock AgentCore](https://github.com/aws-solutions-library-samples/guidance-for-agentic-ai-research-platform-on-aws/blob/main/lib/platform/agent-base-runtime.ts): `lib/platform/agent-base-runtime.ts`
- [Knowledge base](https://github.com/aws-solutions-library-samples/guidance-for-agentic-ai-research-platform-on-aws/blob/main/lib/platform/knowledge-store-stack.ts): `lib/platform/knowledge-store-stack.ts`

### Other components

- **Researcher**
- **Web sources**

## Connections

- Researcher → Research chat: asks research
- Research chat → Chat streaming: submits prompt
- Chat streaming → RPC endpoint: calls execution
- RPC endpoint → Service router: dispatches RPC
- API endpoint → Service router: dispatches API
- Service router → Execution routes: routes execution
- Service router → Thread routes: routes threads
- Service router → Agent routes: routes agents
- Service router → Team routes: routes teams
- Execution routes → Bedrock AgentCore: starts agent runtime
- Bedrock AgentCore → Base agent: runs base agent
- Bedrock AgentCore → Orchestrator: runs orchestrator
- Base agent → Research tools: uses retrieval
- Base agent → Web search: searches web
- Base agent → Code sandbox: runs code
- Orchestrator → Task tools: manages tasks
- Base agent → Task completion: marks task complete
- Task tools → Agent database access: accesses database
- Agent database access → PostgreSQL: reads and writes
- Research tools → Knowledge base: retrieves knowledge
- Web search → Web sources: searches
- Agent setup → Agent routes: configures agents
- Team setup → Team routes: configures teams