The Problem

Developers building AI‑driven assistants need a lightweight, type‑safe framework that can stream LLM responses, call tools, and let callers intercept lifecycle events. Existing monolithic SDKs often force heavy runtimes or hide the hook points that teams want to audit or extend.

What This Does

ia‑agents provides two npm packages:

  • @philschmid/agents‑core – the minimal streaming loop and tool execution engine (packages/agents‑core/src/agent-loop.ts, src/tool.ts).
  • @philschmid/agent – a wrapper that adds a hook system, built‑in tools (file I/O, bash, web‑search, etc.), skill loading, and session management (packages/agent/src/index.ts, src/hooks/*, src/tools/*).

All source files are TypeScript; the public API lives in the src/index.ts files of each package. Documentation and examples are under docs/ and examples/.

How It Is Wired

Execution typically starts at a CLI entry point:

  • examples/cli.ts → imports createAgentSession from packages/agent/src/index.ts.
  • The session constructor (src/context.ts → src/hooks/runner.ts) builds a HooksRunner that registers default hooks and any user‑supplied callbacks.
  • When session.send() is called, the runner invokes agentLoop from packages/agents‑core/src/agent-loop.ts. This function streams interactions to the Gemini model, yields Interaction objects, and, when a tool call is detected, resolves the tool name against the tool registry (packages/agent/src/tools/index.ts).
  • Tool execution is delegated to the concrete implementation in packages/agent/src/tools/<tool>/index.ts (e.g., read-file, bash). Each tool returns a JSON‑serializable result that is fed back into the loop.
  • Hook callbacks (onAgentStart, beforeToolExecute, etc.) are invoked around the loop via HooksRunner (src/hooks/runner.ts). The most widely referenced module is packages/agent/src/tools/index.ts (14 outgoing imports, 4 incoming), making it a hotspot for change impact.
  • The import graph contains two cycles involving packages/agent/src/tools/index.ts and packages/agent/src/tools/subagent/index.ts; breaking these would reduce instability (currently 0.78) and simplify future refactors.

The flow therefore touches four core files (cli.ts, index.ts, agent-loop.ts, tools/index.ts) and spreads outward only through the selected tool modules, keeping the blast radius predictable.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/ia-agents.git
cd ia-agents

# Install dependencies with Bun (preferred) or npm
bun install          # reads package.json and bun.lock
# or: npm ci         # no lockfile present, reproducibility not guaranteed

# Build the two packages
bun run build        # runs the tsup config in each package

# Run a ready‑made example
bun examples/simple.ts

Configuration is type‑safe via packages/agent/src/config.ts. Environment variables prefixed with AGENT_ are merged with a JSON settings.json (if present). No additional secrets are required for the bundled examples.

Real‑World Use

A micro‑service that needs to process user queries could import createAgentSession, register a beforeToolExecute hook to block destructive shell commands, and stream the response back over WebSockets:

import { createAgentSession, printAgentStream } from '@philschmid/agent';

const session = createAgentSession({
  model: 'gemini-3-flash-preview',
  tools: ['read', 'bash', 'web_search'],
});

session.on('beforeToolExecute', ev =>
  ev.toolName === 'bash' && ev.arguments.command?.includes('rm -rf')
    ? { allow: false, reason: 'blocked' }
    : { allow: true }
);

session.send('List recent log files');
await printAgentStream(session.stream(), { verbosity: 'verbose' });

The hook runs in the same process, guaranteeing immediate policy enforcement without an external proxy.

Code Health & Issues

  • High – Pin GitHub Actions – .github/workflows/* uses oven-sh/setup-bun@v2. Replace with a 40‑character commit SHA.
  • High – CI never runs tests – 15 test files exist but no workflow step executes them. Add a bun test step to the existing workflow.
  • Medium – No Dependabot/Renovate – Four manifest files lack an update bot; add .github/dependabot.yml.
  • Medium – No dependency‑vulnerability scan – No dependency-review-action or osv-scanner in CI; add to pull‑request workflow.
  • Low – Missing job timeout – deploy-docs.yml omits timeout-minutes; set a reasonable bound (e.g., 20 min).

Additional observations: the repo has a license, a CI pipeline, but no lockfile for the root package.json, making reproducible builds unreliable. Import cycles in tools/index.ts and tools/subagent/index.ts increase maintenance risk.

The Bottom Line

ia‑agents delivers a clear, modular agent framework with a solid hook system and ready‑to‑use tools, making it suitable for teams that need fine‑grained control over LLM interactions. The codebase is functional but suffers from a few high‑impact health gaps—unpinned actions, missing test execution, and circular imports—that should be addressed before adopting it in production.