> ## Documentation Index
> Fetch the complete documentation index at: https://docs.veadk.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Runner and Execution

`github.com/volcengine/veadk-go/v2/runner` runs agents directly from Go code. It wraps ADK Go Runner and adds default session wiring, long-term memory normalization, saving sessions to memory, final text collection, and multimodal input helpers.

## Minimal Call

Use `RunText` when you only need to send plain text and receive the final visible model response:

```go theme={null}
package main

import (
	"context"
	"fmt"

	veagent "github.com/volcengine/veadk-go/v2/agent/llmagent"
	verunner "github.com/volcengine/veadk-go/v2/runner"
	"google.golang.org/adk/v2/agent"
	"google.golang.org/adk/v2/agent/llmagent"
)

func main() {
	ctx := context.Background()

	a, err := veagent.New(&veagent.Config{
		Config: llmagent.Config{
			Name:        "assistant",
			Description: "Answer short questions.",
			Instruction: "Answer concisely.",
		},
		ModelName: "deepseek-v4-flash-ga-260731",
	})
	if err != nil {
		panic(err)
	}

	r, err := verunner.New(verunner.Config{
		AppName:           "runner_demo",
		Agent:             a,
		AutoCreateSession: true,
	})
	if err != nil {
		panic(err)
	}

	answer, err := r.RunText(ctx, "user_1", "session_1", "hello", agent.RunConfig{})
	if err != nil {
		panic(err)
	}
	fmt.Println(answer)
}
```

`runner.New` requires `Agent`. If `SessionService` is omitted, it defaults to `session.InMemoryService()`. Reuse the same `userID` and `sessionID` for multi-turn conversations.

## Consume Event Streams

Use `Run` when you need streaming UI, tool-call inspection, artifacts, or raw ADK events. `Run` returns an event sequence. Use `CollectFinalText` when you want to collapse an event stream into final text.

```go theme={null}
events := r.Run(ctx, "user_1", "session_2", verunner.UserText("show raw events"), agent.RunConfig{})
for event, err := range events {
	if err != nil {
		return err
	}
	if event.Content == nil {
		continue
	}
	for _, part := range event.Content.Parts {
		if part != nil && !part.Thought && part.Text != "" {
			fmt.Print(part.Text)
		}
	}
}
```

Build multi-part or multimodal input with helper functions:

```go theme={null}
msg := verunner.UserParts(
	genai.NewPartFromText("describe this image"),
	genai.NewPartFromBytes(imageBytes, "image/png"),
)

answer, err := verunner.CollectFinalText(
	r.Run(ctx, "user_1", "image_session", msg, agent.RunConfig{}),
)
```

## Runner Config

| Config | Purpose |
| - | - |
| `AppName` | Application name used for sessions and memory; defaults when omitted. |
| `Agent` | Root agent; required. |
| `SessionService` / `ShortTermMemory` | Short-term session service; two names for the same capability. |
| `ArtifactService` | ADK artifact service for input blobs or produced artifacts. |
| `MemoryService` / `LongTermMemory` | Long-term memory service; two names for the same capability. |
| `PluginConfig` | ADK Runner plugin config, such as observability or auto-save plugins. |
| `AutoCreateSession` | Automatically create missing sessions. |
| `AutoSaveSession` | Install the plugin that saves sessions to long-term memory. |

## context, userID, and sessionID

`context.Context` controls cancellation, deadlines, and request-scoped values. It is not the conversation context. Conversation history is determined by `userID`, `sessionID`, and the configured `SessionService`.

| Value | Recommendation |
| - | - |
| `userID` | Use a business user ID, tenant-scoped user ID, or stable anonymous user ID. |
| `sessionID` | Keep one ID for one conversation; generate a new ID for a new conversation. |
| `context.Context` | Use it for deadlines, cancellation, trace IDs, or request metadata. |

## Direct Runner and Apps

Direct `runner.New` is best when embedding the agent in your own Go flow, such as a backend handler, worker, CLI, or test. `apps/simple_app`, `apps/a2a_app`, and `apps/agentkit_server_app` launch VeADK-provided HTTP, A2A, or AgentKit surfaces.

| Path | Best for |
| - | - |
| Direct `runner.New` | You control request entry, auth, session IDs, and response shape. |
| `apps/simple_app` | Quick local HTTP invocation surface. |
| `apps/a2a_app` | A2A protocol and remote agents. |
| `apps/agentkit_server_app` | AgentKit Runtime or managed platform deployment. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.