# Build an agent

> **📝 Note**
>
> An LLM-optimized bundle of this entire section is available at [`section.md`](https://www.union.ai/docs/v2/union/user-guide/build-agent/section.md).
> This single file contains all pages in this section, optimized for AI coding agent context.

This section covers how to build, deploy, and run agentic AI applications on Union.ai.

Building an agent on Union.ai breaks down into two **orthogonal** choices:

1. **How you build the agent loop** — plain Python, the built-in `flyte.ai.agents.Agent` harness, or a third-party framework (LangGraph, PydanticAI, OpenAI Agents SDK).
2. **How you deploy and run it** — as a task you invoke on demand, as a scheduled task driven by a `flyte.Trigger`, or as a long-running app (e.g. a webhook or chat UI).

Any agent from axis (1) can be deployed via any pattern in axis (2). The two are independent, so you can start with a pure-Python loop run on demand and later move it behind a schedule or a webhook without rewriting the agent.

## How Union.ai maps to the agentic world

- **`TaskEnvironment`**: The sandboxed execution environment for your agent steps. It configures the container image, hardware resources (CPU, GPU), and secrets (API keys). Think of it as defining "where this code runs."
- **`@env.task`**: Turns any Python function into a remotely-executed step. Each task runs in its own container with the resources you specified. This is the equivalent of a node in LangGraph or n8n.
- **Tasks calling tasks**: A task can `await` other tasks, and each called task gets its own container automatically. No separate workflow decorator needed. The calling task IS your workflow, this is how you build multi-step agentic pipelines.
- **`@flyte.trace`**: Marks helper functions inside a task for fine-grained observability and caching. Each traced call appears as a span in the Union.ai dashboard, with its inputs and outputs captured and checkpointed. Use this on your LLM calls, tool executions, and routing decisions to get full visibility into every turn of the agent loop.

> [!TIP]
> See the [Union.ai Quickstart](https://www.union.ai/docs/v2/union/user-guide/quickstart/page.md) for a hands-on walkthrough.

## Ways to build an agent

| Approach | When to use it | Guide |
|----------|----------------|-------|
| **Pure Python** | You want full control over the loop and the lightest possible dependency footprint | [Build an agent with pure Python](https://www.union.ai/docs/v2/union/user-guide/build-agent/python-agents/page.md) |
| **The `Agent` harness** | You want a batteries-included tool-use loop with tools, MCP servers, memory, and HITL built in | [The Flyte Agent harness](https://www.union.ai/docs/v2/union/user-guide/build-agent/flyte-agents/page.md) |
| **Third-party frameworks** | You already have agents written with LangGraph, PydanticAI, or the OpenAI Agents SDK | [Agent framework integrations](https://www.union.ai/docs/v2/union/user-guide/agent-framework-integrations/_index) |

The `Agent` harness has a few dedicated guides of its own:

- [**Extend the Agent class**](https://www.union.ai/docs/v2/union/user-guide/build-agent/flyte-agents/page.md#extending-the-agent-class): customize the loop by overriding `run`.
- [**Agent memory**](https://www.union.ai/docs/v2/union/user-guide/build-agent/agent-memory/page.md): persist conversation history and artifacts across runs with `MemoryStore`.
- [**Add a chat UI**](https://www.union.ai/docs/v2/union/user-guide/build-agent/agent-chat-ui/page.md): give any agent a hosted chat interface.

## Deploying an agent

Once you've built an agent, [**Deploy an agent as a service**](https://www.union.ai/docs/v2/union/user-guide/build-agent/deploy-agent-as-service/page.md) covers running it as a task, on a schedule via `flyte.Trigger`, and behind an `AppEnvironment` webhook.

## Related

- [**Sandboxing**](https://www.union.ai/docs/v2/union/user-guide/sandboxing/_index): safely execute LLM-generated code.
- [**Build an MCP server**](https://www.union.ai/docs/v2/union/user-guide/build-mcp/_index): serve Model Context Protocol servers for AI assistants to interact with Union.ai.

## Subpages

- [Pure Python agents](https://www.union.ai/docs/v2/union/user-guide/build-agent/python-agents/page.md)
  - ReAct pattern: Reason, Act, Observe (no framework needed)
  - Plan-and-Execute with parallel fan-out
  - More agentic patterns
  - How Union.ai's primitives map to the agent stack
  - Next steps
- [Flyte-native agents](https://www.union.ai/docs/v2/union/user-guide/build-agent/flyte-agents/page.md)
  - How it works
  - Sync vs async
  - A minimal agent
  - Tools
  - Customizing a tool with `tool(...)`
  - MCP integration
  - Skills
  - Observability
  - Extending the agent class
  - `run` is sync-by-default
  - Strategy 1: wrap the built-in loop
  - Strategy 2: implement `run` from scratch
  - Choosing between subclassing and composition
  - Next steps
- [Agent memory](https://www.union.ai/docs/v2/union/user-guide/build-agent/agent-memory/page.md)
  - What a `MemoryStore` holds
  - Sync vs async
  - Keyed stores: the easy path
  - Working with a MemoryStore independently
  - Optimistic concurrency
  - Optional capabilities
  - Passing memory to the agent
  - Lower-level usage
  - Next steps
- [Agent chat UI](https://www.union.ai/docs/v2/union/user-guide/build-agent/agent-chat-ui/page.md)
  - Option 1: the built-in chat UI
  - Option 2: a custom FastAPI chat app
  - Next steps
- [Deploy an agent as a service](https://www.union.ai/docs/v2/union/user-guide/build-agent/deploy-agent-as-service/page.md)
  - As a task
  - As a scheduled task (via `Trigger`)
  - Behind a webhook (`AppEnvironment`)
  - Chat and other app patterns

---
**Source**: https://github.com/unionai/unionai-docs/blob/main/content/user-guide/build-agent/_index.md
**HTML**: https://www.union.ai/docs/v2/union/user-guide/build-agent/