Execution engine

Runner executes an agent and connects it to sessions, tools, and tracing. VeADK adds the convenient run() entry point on top of Google ADK’s event execution interface. Use run_async() when you need to process individual events

Minimal run

Complete installation and model configuration. Save as app.py and run python app.py; the terminal should print the model’s text response

app.py

import asyncio
from veadk import Agent, Runner

agent = Agent(name="assistant")
runner = Runner(agent=agent, app_name="demo", user_id="demo-user")

async def main():
    response = await runner.run(
        "Explain the purpose of an agent in one sentence", session_id="demo-session"
    )
    print(response)

asyncio.run(main())

run() is asynchronous: call it with await or asyncio.run(). Sessions use process memory by default. Reusing the application, user, and session identifiers continues a conversation; in-memory sessions disappear when the process exits

Assign an explicit session_id to each conversation instead of relying on the default temporary value to generate independent sessions. run() returns the last retained text part and may return an empty string. Use run_async() for multipart output, tool events, and complete structured results

Multi-tenant isolation

app_name, user_id, and session_id locate data; they do not authenticate users or authorize access. Obtain user identifiers from verified request identities instead of trusting arbitrary client-provided user_id values

Data	Identifiers and scope
Short-term sessions	Located by `app_name`, `user_id`, and `session_id`; persistence depends on the session backend
Long-term memory	User filtering depends on the memory backend; the local backend does not isolate by `user_id`
Knowledge bases	Scope depends on the selected knowledge base, collection, and backend query; `app_name` does not automatically enforce tenant authorization

Streaming events

run_async() returns an asynchronous event stream. Unlike run(), it requires an existing session. This example requests streaming with StreamingMode.SSE but prints only complete responses to avoid displaying both partial chunks and the same complete text

stream.py

import asyncio
from google.adk.agents.run_config import RunConfig, StreamingMode
from google.genai.types import Content, Part
from veadk import Agent, Runner

APP_NAME, USER_ID, SESSION_ID = "stream_demo", "demo-user", "demo-session"
runner = Runner(
    agent=Agent(name="assistant"), app_name=APP_NAME, user_id=USER_ID
)

async def main():
    await runner.session_service.create_session(
        app_name=APP_NAME, user_id=USER_ID, session_id=SESSION_ID
    )
    message = Content(role="user", parts=[Part(text="Explain the purpose of an agent in one sentence")])
    async for event in runner.run_async(
        user_id=USER_ID,
        session_id=SESSION_ID,
        new_message=message,
        run_config=RunConfig(streaming_mode=StreamingMode.SSE),
    ):
        if event.error_code:
            print("Error:", event.error_code, event.error_message)
        for call in event.get_function_calls():
            print("Tool call:", call.name)
        for result in event.get_function_responses():
            print("Tool result:", result.name)
        if event.partial:
            continue
        if event.is_final_response() and event.content:
            text = "".join(
                part.text for part in (event.content.parts or [])
                if part.text and not part.thought
            )
            if text:
                print(text)

asyncio.run(main())

Save as stream.py and run python stream.py. If tools are configured, the terminal also displays tool call and result names. Incremental output depends on model and runtime support; consuming events does not mean every runtime returns individual tokens To display text incrementally, use partial=True events to update the current response and replace it with the complete text when that event arrives. Do not append both forms to the same output

Parsing events

Field or method	Description
`author`	Event producer
`content.parts`	Text, tool calls, tool results, or multimodal data; may be empty
`partial`	Whether this is an incomplete incremental chunk
`usage_metadata`	Usage reported by the model; may be absent
`invocation_id`	Identifier for this execution
`error_code`, `error_message`	Error details carried by an event; execution can also raise an error directly
`is_final_response()`	Whether the event is a complete response suitable for display; multi-agent flows can produce several responses
`get_function_calls()`	Tool calls in this event
`get_function_responses()`	Tool results in this event

part.text contains text, part.thought marks reasoning content, and part.function_call and part.function_response represent tool calls and results. Handle each content type separately when displaying results. Avoid printing complete tool arguments that may contain credentials or sensitive data

Parameters and behavior

Runner constructor

Parameter	Type	Default	Description
`agent`	`BaseAgent`	`None`	Agent to execute; normally a VeADK `Agent`
`short_term_memory`	`ShortTermMemory`	From the agent, otherwise in-memory sessions	Pass explicitly when the root agent is not a VeADK agent
`app_name`	`str`	`veadk_default_app`	Application identifier; an explicit ADK `app` supplies its own name
`user_id`	`str`	`veadk_default_user`	Default user for `run()`
`upload_inline_data_to_tos`	`bool`	`False`	Upload inline media to TOS; requires credentials and resource permissions and may incur charges
`run_processor`	`BaseRunProcessor`	Agent configuration, otherwise no interception	Runner-level processor; see Outbound authentication for authentication use

ADK’s session_service, memory_service, and credential_service can be supplied as keyword arguments. Explicit services take precedence over agent configuration. When supplying a session service, create sessions through that service and use run_async() so creation and reads use the same backend. See the Runner reference for other ADK parameters

run parameters

Parameter	Type	Default	Description
`messages`	`str`, `MediaMessage`, or a list of either	Required	User input; lists run sequentially
`user_id`	`str`	Empty string	Uses the Runner user when empty
`session_id`	`str`	Temporary identifier	Supply explicitly; reuse it to continue a conversation
`run_config`	`RunConfig`	`None`	If omitted, the model-call limit uses `MODEL_AGENT_MAX_LLM_CALLS`, default `100`
`save_tracing_data`	`bool`	`False`	Save data from configured tracers after execution
`upload_inline_data_to_tos`	`bool`	`False`	Enable media upload for this call
`run_processor`	`BaseRunProcessor`	`None`	Per-call processor, taking precedence over the Runner setting

VeADK run() returns an empty string when the model-call limit is reached. To distinguish this from a response without text or other failures, consume run_async() events and handle execution errors

Overview

Get started

Core components

Observability

Extensions

Frontend

Security

Deployment

Minimal run

Multi-tenant isolation

Streaming events

Parsing events

Parameters and behavior

Runner constructor

run parameters

​Minimal run

​Multi-tenant isolation

​Streaming events

​Parsing events

​Parameters and behavior

​Runner constructor

​run parameters

Minimal run

Multi-tenant isolation

Streaming events

Parsing events

Parameters and behavior

Runner constructor

run parameters