runtime
runtime is a standalone Go module containing reusable agent runtime packages extracted from norma.
The repo stays as one Go module. The root import path github.com/normahq/runtime/v2 is documentation-only; functional APIs live in the subpackages.
Start Here
- Use
agentfactory when you want to build runtime agents from validated provider config.
- Use
appconfig when you need config-file loading, profile overlays, and runtime validation.
- Use
agentconfig when you already have decoded config and need schema validation or normalization.
- Use
agentfactory with ACP provider config when you need ACP subprocess-backed agents.
- Use
hostedagent when you want to wrap a local API-backed model as an ADK agent.
- Use
poolagent to provide ordered failover across providers.
- Use
structuredagent to enforce JSON-schema-constrained I/O.
- Use
mcpregistry and sessionstate as low-level support packages.
Installation
go get github.com/normahq/runtime/v2
Packages
github.com/normahq/runtime/v2/agentconfig
github.com/normahq/runtime/v2/agentfactory
github.com/normahq/runtime/v2/appconfig
github.com/normahq/runtime/v2/hostedagent
github.com/normahq/runtime/v2/mcpregistry
github.com/normahq/runtime/v2/poolagent
github.com/normahq/runtime/v2
github.com/normahq/runtime/v2/sessionstate
github.com/normahq/runtime/v2/structuredagent
github.com/normahq/runtime/v2/taskmaster
github.com/normahq/runtime/v2/taskmaster/adk
Usage
OpenAI-compatible request options
OpenAI-compatible providers use a 30-second HTTP request timeout by default. Set
runtime.providers.<name>.openai.timeout to a positive Go duration when a
provider needs longer requests:
runtime:
providers:
deepseek:
type: openai
openai:
api_key: ${DEEPSEEK_API_KEY}
model: deepseek-v4-pro
timeout: 180s
reasoning_effort: none
reasoning_effort is the same config field name used by ACP providers. For
OpenAI-compatible providers, only none is currently supported; it sends
thinking.type=disabled on the wire. The field is omitted by default. Set it
only for providers that accept thinking.type. Higher effort levels require
reasoning content to survive tool-call turns.
Validate runtime settings
package main
import (
"fmt"
"github.com/normahq/runtime/v2/appconfig"
)
func main() {
settings := map[string]any{
"providers": map[string]any{
"codex": map[string]any{
"type": "codex_acp",
"codex_acp": map[string]any{
"bridge_version": "latest",
},
},
},
}
if err := appconfig.ValidateSettings(settings); err != nil {
panic(err)
}
fmt.Println("runtime config is valid")
}
Build an agent from provider config
package main
import (
"context"
"github.com/normahq/runtime/v2/agentconfig"
"github.com/normahq/runtime/v2/agentfactory"
"github.com/normahq/runtime/v2/mcpregistry"
)
func main() {
providers := map[string]agentconfig.Config{
"codex": {
Type: agentconfig.AgentTypeCodexACP,
CodexACP: &agentconfig.ACPConfig{
BridgeVersion: "1.10.1",
},
},
}
factory := agentfactory.New(providers, mcpregistry.New(nil))
_, err := factory.Build(context.Background(), agentfactory.BuildRequest{
AgentID: "codex",
WorkingDirectory: "/workspace",
})
if err != nil {
panic(err)
}
}
For codex_acp, bridge_version accepts an npm version or dist-tag for
the canonical codex-acp package;
empty defaults to the tested 1.10.1 release. The configuration field keeps
its existing name for compatibility.
registry_acp allows running any agent from the official ACP Registry
by specifying registry_id (e.g. amp-acp, cline, auggie, codebuddy, claude-acp, etc.).
It runs the agent via @baldaworks/acprun (defaulting to pinned 0.1.6, customizable via bridge_version).
agy_acp (and compatibility alias antigravity_acp) runs the Google Antigravity CLI ACP
agent (antigravity-acp) via @baldaworks/acprun.
model and reasoning_effort are explicit ACP session settings. Runtime applies
them after session/new or session/resume, so configured values replace
conflicting persisted values for the same option IDs. model_config_id defaults
to model, and reasoning_effort_config_id defaults to reasoning_effort.
Set the exact IDs advertised by a custom ACP server when they differ, for
example reasoning_effort_config_id: thought_level. Omitted settings remain
session-controlled. This behavior is shared by every ACP-backed provider config.
claude_acp is a compatibility alias for claude_code_acp. Both use the same
claude_code_acp configuration block.
grok_acp runs Grok Build through grok agent stdio by default. The Grok CLI
must be authenticated with grok login or XAI_API_KEY.
gemini_acp is deprecated and no longer supported. Use another supported ACP
provider type, or configure Gemini explicitly through generic_acp if you need
a custom ACP command path.
Direct ACP agent construction lives in github.com/normahq/go-adk-acpagent/v2.
Runtime v2 uses that package internally through agentfactory.
Migration Notes
github.com/normahq/runtime/... imports move to github.com/normahq/runtime/v2/....
github.com/normahq/norma/pkg/runtime/... imports move to github.com/normahq/runtime/v2/....
- ADK imports must use
google.golang.org/adk/v2/....
- The old
github.com/normahq/runtime/acpagent package is removed; use github.com/normahq/go-adk-acpagent/v2.
- The old
providererror package is removed.
agentconfig.MCPServerConfig gained DedupKey and DedupPreferred. Both are
additive and default to off. They replace the earlier behaviour where the
runtime collapsed MCP endpoints that shared a host and path: query parameters
and headers can select a tenant or an authorization context, so equivalence is
now declared by the caller instead of inferred from the URL.
See MIGRATION.md for the local consumer audit.
Development
go mod tidy
go test ./...
go test -race ./...
go tool golangci-lint run ./...
task docs:check
task docs:generate
Go Doc
The source comments and example tests are the source of truth for package documentation.
Generate local docs from source:
task docs:generate
Validate that every public package has package docs and renders with go doc:
task docs:check
Generated output is written to .cache/godoc/ and is not committed.
See AGENTS.md for repository-specific guidance.