Execution engine

Runner is the core of the execution engine: it coordinates the agent, tools, and callbacks to respond to user input, while managing the flow of information, state changes, and interactions with the model, tools, and storage. VeADK’s execution engine is fully compatible with Google ADK’s Runner; see the Google ADK runtime docs for its full mechanics.

Multi-tenant isolation

For enterprise multi-tenant scenarios, Runner isolates data along three dimensions — app_name, user_id, and session_id:

Data	Isolation dimensions
Short-term session	`app_name`, `user_id`, `session_id`
Long-term memory	`app_name`, `user_id`
Knowledge base	`app_name`

Minimal run

Runner.run() runs an agent directly, handling input and returning the final text response — convenient for local testing:

import asyncio
from veadk import Agent, Runner

agent = Agent()
runner = Runner(agent=agent)

response = asyncio.run(runner.run("What's the weather in Beijing?"))
print(response)

run() is high-level. When the Runner has a short-term session configured, it creates the session on demand. For finer-grained control over execution, use run_async().

Use Harness execution enhancements

VeADK 1.0.1 provides Harness plugins that attach to Runner to prepare context before each turn, compact large tool results, and check whether final answers are supported by tool results. The base plugins ship with VeADK. Install the harness extra when using the Headroom compaction provider:

pip install "veadk-python[harness]==1.0.1"

from veadk import Agent, Runner
from veadk.extensions.harness.plugins import build_harness_plugins

agent = Agent(name="research_agent")
runner = Runner(
    agent=agent,
    app_name="research",
    plugins=build_harness_plugins(
        components=["invocation_context", "compactor", "response_verification"],
        profile="research",
    ),
)

Component	Purpose
`invocation_context`	Prepares task anchors, recent context, and tool-use constraints.
`compactor`	Compacts oversized tool results while retaining task-relevant facts.
`response_verification`	Records tool results and checks whether key final claims are supported.

Discover remote agents from AgentKit

When deploying a Harness service, enable AgentKit A2A Registry to discover matching remote agents from an agent center for each turn:

export REGISTRY_TYPE="agentkit_a2a"
export REGISTRY_SPACE_ID="your-agent-center-id"
export REGISTRY_TOP_K="3"

REGISTRY_TOP_K limits the candidates retrieved per turn and defaults to 3. The runtime needs access to AgentKit A2A Registry. When a remote Agent Card declares authentication, it also needs the corresponding API key or Identity OpenAPI permissions. See Outbound authentication for OAuth2 remote calls.

Streaming events

Runner.run_async() returns an async generator that yields the events produced during the agent’s run. Unlike run(), which only returns the final text, iterating over events gives you the reasoning, tool calls and results, and streaming increments — useful for building your own logic on top.

import asyncio
from google.genai.types import Content, Part
from veadk import Agent, Runner

APP_NAME, USER_ID, SESSION_ID = "app", "user", "session"

agent = Agent()
runner = Runner(agent=agent, app_name=APP_NAME, user_id=USER_ID)

message = Content(role="user", parts=[Part(text="What's the weather in Beijing?")])

async def main():
    async for event in runner.run_async(
        user_id=USER_ID,
        session_id=SESSION_ID,
        new_message=message,
    ):
        ...  # see "Parsing events" below

asyncio.run(main())

run_async() requires the session to exist beforehand. If you call it directly, make sure the session for session_id has been created.

Parsing events

Each event describes one step of the run. Its common fields:

Field	Description
`author`	Name of the agent or tool that produced the event
`content`	Event content, with a `role` and a `parts` list
`partial`	Whether this is a streaming increment
`usage_metadata`	Token usage for this step
`invocation_id`	Identifier of this invocation

Each part in content.parts may be a different type; branch on it:

part field	Meaning
`text`	Text output by the model
`thought`	Marks the part as the model’s reasoning
`function_call`	A tool call from the model, with `name` and `args`
`function_response`	A tool result, with `name` and `response`

The event also offers helpers: is_final_response() tells whether it is the final reply, and get_function_calls() / get_function_responses() extract the tool calls and results from the event.

async for event in runner.run_async(
    user_id=USER_ID, session_id=SESSION_ID, new_message=message,
):
    # Tool calls and results
    for call in event.get_function_calls():
        print("tool call:", call.name, call.args)
    for resp in event.get_function_responses():
        print("tool result:", resp.name, resp.response)

    # Distinguish reasoning from text
    if event.content:
        for part in event.content.parts:
            if part.thought:
                continue  # the model's reasoning; display if desired
            if part.text:
                print(part.text)

    # Final reply
    if event.is_final_response() and event.content:
        final_text = "".join(p.text for p in event.content.parts if p.text)

Overview

Get started

Core components

Observability

Extensions

Frontend

Security

Multi-tenant isolation

Minimal run

Use Harness execution enhancements

Discover remote agents from AgentKit

Streaming events

Parsing events

​Multi-tenant isolation

​Minimal run

​Use Harness execution enhancements

​Discover remote agents from AgentKit

​Streaming events

​Parsing events

Multi-tenant isolation

Minimal run

Use Harness execution enhancements

Discover remote agents from AgentKit

Streaming events

Parsing events