Skip to content

Full-stack agents

Genkit agents package the model loop, message history, tool calls, streaming, and persistence behind one API. You define the agent on the server, then call the same conversational interface in process or through HTTP.

Genkit agents are useful when your app needs an assistant, an approval workflow, a long-running generator, or a coordinator that delegates work to specialized agents. They build on Genkit prompts and generate() calls, so they can use models, tools, middleware, and developer tooling from the rest of Genkit.

When to choose Genkit agents

Section titled “When to choose Genkit agents”

Use standard Genkit flows and generate() primitives when you want full control over the application’s API shape, persistence model, orchestration, and frontend protocol. A flow is often the right fit for request and response tasks, explicit backend workflows, scheduled jobs, and systems where your app already owns every step of state management.

Use Genkit agents when the feature is naturally conversational or iterative. They handle the repeated work that chat-based applications need, including message history, streaming updates, tool turns, snapshots, aborts, interrupts, background execution, and continuation from a previous turn. They are a strong fit for persistent chat applications, conversational product experiences, approval workflows, task copilots, and multi-turn generation where the model refines output over several steps.

Genkit agents are also designed for seamless frontend integration. A browser or mobile client can use the same chat() interface for local and remote agents, receive streamed text, state patches, artifacts, and tool interruptions, then continue the next turn without rebuilding the transport protocol. You can build the same capabilities with flows and generate() if you need maximum architectural control, but agents remove much of the plumbing for persistent, interactive AI features.

The Agents API is available in Genkit Python. It supports local agents, server-managed session stores, FastAPI HTTP serving, custom state, tool interrupts, background detached work, and remote agent clients.

Import the experimental entrypoints from genkit.exp (Genkit, current_session), agent types and session stores from genkit.exp.agent, and FastAPI routes from genkit_fastapi.exp. The samples in this section are based on the Python agents samples.

Your first agent

Section titled “Your first agent”
from genkit.exp import Genkit
from genkit_google_genai import GoogleAI


ai = Genkit(plugins=[GoogleAI()])


assistant = ai.define_agent(
    name='assistant',
    model=GoogleAI.gemini('gemini-flash-latest'),
    system='You are a helpful assistant.',
)


async def main() -> None:
    chat = assistant.chat()
    res = await chat.send('Hello. What can you do?')
    print(res.text)
    # => I can answer questions, summarize text, and help with tasks.


if __name__ == '__main__':
    ai.run_main(main())

Common path

Section titled “Common path”

Most production agents grow in this order:

  1. Define the agent with a model, system instructions, and tools.
  2. Call it locally with chat().send() or chat().send_stream().
  3. Add a session store (InMemorySessionStore or FileSessionStore from genkit.exp.agent, or FirestoreSessionStore from genkit_google_cloud.exp) when the server should own history.
  4. Serve it over HTTP with FastAPI using serve_agent() from genkit_fastapi.exp.
  5. Call the agent from a remote client using remote_agent() from genkit.exp.agent.

Develop with the Genkit Dev UI

Section titled “Develop with the Genkit Dev UI”

The Genkit Developer UI lets you chat with your agents, inspect their full execution, and iterate quickly without writing any frontend code. When you run your app with the Genkit CLI, agents appear alongside your flows, prompts, and models so you can send messages, watch streamed responses, step through tool calls, and review session state.

Chatting with a Genkit agent in the Developer UI

This makes the Dev UI a fast way to test conversational behavior, debug tool turns, and verify interrupts and continuation before wiring up a client. You can also inspect detailed execution traces for each turn to see model calls, tool invocations, latency, and token usage.

Where to go next

Section titled “Where to go next”
  • Define agents covers define_agent, define_prompt_agent, define_custom_agent, tools, and schemas.
  • Run and stream covers chat(), load_chat(), send(), send_stream(), foreground cancellation, and failed turns.
  • Serve over HTTP covers FastAPI routes with serve_agent() and remote_agent().
  • Sessions and state covers stores, custom state, and functional state updates.
  • Session stores covers InMemorySessionStore, FileSessionStore, and FirestoreSessionStore.
  • Interrupts covers tool interrupts and resume.
  • Background execution covers detached work (detach), polling, and aborting.
  • Multi-agent delegation covers delegation tools that run a turn on a specialist agent.
  • Custom orchestration covers define_custom_agent and custom turn loops.
  • Error handling covers failed turns, GenkitError, and recovering last-good state.